added qse_sed_getspace(), qse_sed_allocmem(), qse_sed_reallocmem(), qse_sed_callocmem(), qse_sed_freemem()

qse/include/qse/awk/std.h

@@ -65,14 +65,20 @@ struct qse_awk_parsestd_t
 		} file;
 
 		/** 
+		 * input string or dynamically allocated output string
+		 *
 		 * For input, the ptr and the len field of str indicates the 
-		 * pointer and the length of a string to read.
+		 * pointer and the length of a string to read. You must set
+		 * these fields before calling qse_awk_parsestd().
 		 *
 		 * For output, the ptr and the len field of str indicates the
 		 * pointer and the length of a deparsed source string. The output
-		 * string is dynamically allocated. You must free this output 
-		 * pointer using #QSE_MMGR_FREE once you're done with it to avoid 
-		 * memory leaks. 
+		 * string is dynamically allocated. You don't need to set these
+		 * fields before calling qse_awk_parsestd() because they are set
+		 * by qse_awk_parsestd() and valid while the relevant awk object
+		 * is alive. You must free the memory chunk pointed to by the
+		 * ptr field with qse_awk_freemem() once you're done with it to 
+		 * avoid memory leaks. 
 		 */
 		qse_xstr_t str;
 	} u;

qse/include/qse/sed/Sed.hpp

@@ -34,9 +34,9 @@
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
 
-/**
- * The Sed class implements a stream editor by wrapping around #qse_sed_t.
- */
+///
+/// The Sed class implements a stream editor by wrapping around #qse_sed_t.
+///
 class QSE_EXPORT Sed: public Mmged
 {
 public:
@@ -60,7 +60,7 @@ public:
 #endif
 
 	///
-	/// The Stream class is a base class for I/O operation during
+	/// The Stream class is a abstract class for I/O operation during
 	/// execution.
 	///
 	class QSE_EXPORT Stream: public Types

qse/include/qse/sed/StdSed.hpp

@@ -34,16 +34,19 @@
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
 
-/**
- * The StdSed class inherits the Sed class, implements a standard
- * I/O stream class, and sets the default memory manager.
- *
- */
+///
+/// The StdSed class inherits the Sed class, implements a standard
+/// I/O stream class, and sets the default memory manager.
+///
 class QSE_EXPORT StdSed: public Sed
 {
 public:
 	StdSed (Mmgr* mmgr = StdMmgr::getDFL()): Sed (mmgr) {}
 
+	///
+	/// The FileStream class implements a stream over input
+	/// and output files.
+	///
 	class QSE_EXPORT FileStream: public Stream
 	{
 	public:
@@ -65,6 +68,9 @@ public:
 		qse_cmgr_t*   cmgr;
 	};
 
+	///
+	/// The StringStream class implements a stream over a string
+	///
 	class QSE_EXPORT StringStream: public Stream
 	{
 	public:
@@ -96,19 +102,6 @@ public:
 	};
 };
 
-/** 
- * @example sed02.cpp 
- * The example shows how to use the QSE::StdSed class to write a simple stream
- * editor that reads from a standard input or a file and writes to a standard 
- * output or a file.
- */
-
-/**
- * @example sed03.cpp 
- * The example shows how to extend the QSE::StdSed class to read from and 
- * write to a string.
- */
-
 /////////////////////////////////
 QSE_END_NAMESPACE(QSE)
 /////////////////////////////////

qse/include/qse/sed/sed.h

@@ -44,11 +44,6 @@
  *
  */
 
-/**
- * @example sed.c
- * This example shows how to write a basic stream editor.
- */
-
 /** @struct qse_sed_t
  * The qse_sed_t type defines a stream editor. The structural details are 
  * hidden as it is a relatively complex data type and fragile to external
@@ -388,6 +383,17 @@ typedef void (*qse_sed_exec_tracer_t) (
 );
 #endif
 
+/**
+ * The qse_sed_space_t type defines the types of
+ * sed bufferspaces. 
+ */
+enum qse_sed_space_t
+{
+	QSE_SED_SPACE_HOLD,   /**< hold space */
+	QSE_SED_SPACE_PATTERN /**< pattern space */
+};
+typedef enum qse_sed_space_t qse_sed_space_t;
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -653,6 +659,44 @@ QSE_EXPORT void qse_sed_setlinenum (
 	qse_size_t num    /**< a line number */
 );
 
+
+/**
+ * The qse_sed_allocmem() function allocates a chunk of memory using
+ * the memory manager of \a sed.
+ */
+QSE_EXPORT void* qse_sed_allocmem (
+	qse_sed_t* sed,
+	qse_size_t size
+);
+
+/**
+ * The qse_sed_allocmem() function allocates a chunk of memory using
+ * the memory manager of \a sed and clears it to zeros.
+ */
+QSE_EXPORT void* qse_sed_callocmem (
+	qse_sed_t* sed,
+	qse_size_t size
+);
+
+/**
+ * The qse_sed_allocmem() function reallocates a chunk of memory using
+ * the memory manager of \a sed.
+ */
+QSE_EXPORT void* qse_sed_reallocmem (
+	qse_sed_t* sed,
+	void*      ptr,
+	qse_size_t size
+);
+
+/**
+ * The qse_sed_allocmem() function frees a chunk of memory using
+ * the memory manager of \a sed.
+ */
+QSE_EXPORT void qse_sed_freemem (
+	qse_sed_t* sed,
+	void*      ptr
+);
+
 #ifdef QSE_ENABLE_SEDTRACER
 /**
  * The qse_sed_getexectracer() function returns the execution tracer 
@@ -663,7 +707,7 @@ QSE_EXPORT qse_sed_exec_tracer_t qse_sed_getexectracer (
 );
 
 /**
- * The qse_sed_getexectracer() function sets a hook function via which 
+ * The qse_sed_setexectracer() function sets a hook function via which 
  * you can trace commands being executed.
  */
 QSE_EXPORT void qse_sed_setexectracer (
@@ -672,6 +716,16 @@ QSE_EXPORT void qse_sed_setexectracer (
 );
 #endif
 
+/**
+ * The qse_sed_getspace() function gets the pointer and the length
+ * to a buffer space specfied by \a space.
+ */
+QSE_EXPORT void qse_sed_getspace (
+	qse_sed_t*      sed,
+	qse_sed_space_t space,
+	qse_cstr_t*     str
+);
+
 #ifdef __cplusplus
 }
 #endif

qse/include/qse/sed/std.h

@@ -30,10 +30,6 @@
  * you can choose to use the helper functions provided here. It is  
  * a higher-level interface that is easier to use as it implements 
  * default handlers for I/O and memory management.
- *
- * @example sed01.c
- * This example shows how to write a simple stream editor using easy API 
- * functions.
  */
 
 /**
@@ -54,17 +50,43 @@ typedef enum qse_sed_iostd_type_t qse_sed_iostd_type_t;
  */
 struct qse_sed_iostd_t
 {
-	qse_sed_iostd_type_t type;  /**< resource type */
+	/** resource type */
+	qse_sed_iostd_type_t type;
+
+	/** union describing the resource of the specified type */
 	union
 	{
+		/** file path with character encoding */
 		struct
 		{
-			const qse_char_t* path; /**< file path */
-			qse_cmgr_t*       cmgr; /**< cmgr for the file */
+			/** file path to open. #QSE_NULL or '-' for stdin/stdout. */
+			const qse_char_t*  path;
+			/** a stream created with the file path is set with this
+			 * cmgr if it is not #QSE_NULL. */
+			qse_cmgr_t*  cmgr;
 		} file; 
+
+		/** 
+		 * input string or dynamically allocated output string
+		 *
+		 * For input, the ptr and the len field of str indicates the 
+		 * pointer and the length of a string to read. You must set
+		 * these two fields before calling qse_sed_execstd().
+		 *
+		 * For output, the ptr and the len field of str indicates the
+		 * pointer and the length of produced output. The output
+		 * string is dynamically allocated. You don't need to set these
+		 * fields before calling qse_sed_execstd() because they are
+		 * set by qse_sed_execstd() and valid while the relevant sed
+		 * object is alive. You must free the memory chunk pointed to by
+		 * the ptr field with qse_sed_freemem() once you're done with it
+	      * to avoid memory leaks. 
+           */
 		qse_xstr_t        str;
+
+		/** pre-opened sio stream */
 		qse_sio_t*        sio;
-	} u; /**< union containing data for each type */
+	} u;
 };
 
 typedef struct qse_sed_iostd_t qse_sed_iostd_t;