updated docs

qse/doc/Makefile.am

@@ -7,8 +7,6 @@ EXTRA_DIST = \
 	page/mainpage.md \
 	page/installation.md \
 	page/mem.doc \
-	page/cenc.doc \
-	page/io.doc \
 	page/awk-embed.md \
 	page/awk-lang.md \
 	page/sed-cmd.md \

qse/doc/Makefile.in

@@ -234,8 +234,6 @@ EXTRA_DIST = \
 	page/mainpage.md \
 	page/installation.md \
 	page/mem.doc \
-	page/cenc.doc \
-	page/io.doc \
 	page/awk-embed.md \
 	page/awk-lang.md \
 	page/sed-cmd.md \

qse/doc/page/awk-embed.md

@@ -121,11 +121,12 @@ the same function multiple times.
 
  \includelineno awk06.c
 
-Similarly, you can pass a more complex value than a number. You can compose
+Similarly, you can pass a more complex value than a plain number or string. 
-a map value with qse_awk_rtx_makemapval() or qse_awk_rtx_makemapvalwithdata().
+You can compose a map value with qse_awk_rtx_makemapval() or 
-The sample below demonstrates how to use qse_awk_rtx_makemapvalwithdata(),
+qse_awk_rtx_makemapvalwithdata(). The following sample demonstrates how to
-pass a created map value to qse_awk_rtx_call(), and traverse a map value
+use qse_awk_rtx_makemapvalwithdata(), pass a created map value to 
-returned with qse_awk_rtx_getfirstmapvalitr() and qse_awk_rtx_getnextmapvalitr().
+qse_awk_rtx_call(), and traverse a map value returned with 
+qse_awk_rtx_getfirstmapvalitr() and qse_awk_rtx_getnextmapvalitr().
 
  \includelineno awk07.c
 
@@ -144,9 +145,9 @@ variables are available as the ::qse_awk_gbl_id_t type values
 Built-in Functions
 ------------------
 
-QSEAWK predefines built-in functions like *match*. You can add your own 
+QSEAWK predefines built-in functions like *match* and *gsub*. You can add your
-built-in function with qse_awk_addfnc(). The following sample shows how to add
+own built-in function with qse_awk_addfnc(). The following sample shows how to 
-a function named *basename* that get the base file name part of a path name.
+add a function named *basename* that get the base file name part of a path name.
 
  \includelineno awk09.c
 
@@ -156,26 +157,62 @@ with an error since it returned -1. To avoid the situation, you may change
 the way basename() works by defining it to return the resulting string via
 the second parameter and return 0 or -1 as a return value. For the arguements
 to pass by reference, you can specify the letter *r* into the *arg.spec* field
-at the argument position.
+at the argument position. That is, speciying *r* at the second position in
+the *arg.spec* string means that you want to pass the second argument by
+reference.
 
  \includelineno awk10.c
 
-Single Script over Multiple Data Streams
+Customizing Other Behaviors
-----------------------------------------
+---------------------------
 
-Customizing Language Features
+QSEAWK comes with more more trait options that you can use to change the
------------------------------
+behavior. For instance, you have seen how to disable the standard BEGIN, 
+END, pattern-action blocks by turning off the #QSE_AWK_PABLOCK trait option
+in several sample program above. 
 
-Creating multiple awk objects
+The ::qse_awk_trait_t type defines various trait options that you can turn
------------------------------
+on or off using qse_awk_setopt() with #QSE_AWK_TRAIT. The following code 
+snippet shows how to disable all built-in I/O statements like *getline*, 
+*print*, *printf*, *close*, *fflush*, piping, and file redirection. 
+Additionally, it disables the BEGIN, END, pattern-action blocks.
+
+~~~~~{.c}
+ qse_awk_getopt (awk, QSE_AWK_TRAIT, &opt);
+ opt &= ~QSE_AWK_PABLOCK;
+ opt &= ~QSE_AWK_RIO;
+ qse_awk_setopt (awk, QSE_AWK_TRAIT, &opt);
+~~~~~
+
+This way, you can change the QSEAWK language behave differently for your
+own needs.
+
+Multiple Instances
+------------------
+
+The awk object and the runtime context object reside in its own memory blocks
+allocated and maintain related information in their own object space. Multiple
+instances created are independent of each other.
+
+You can run a script over multiple data streams by creating multiple runtime
+context objects from a single awk object.
+
+TBD.
 
 Memory Pool
 -----------
 
+You can confine the information used for an awk object include the related
+runtime context objects in a single memory pool.
+
+TBD.
+
 Writing Modules
 ---------------
 
-modular built-in functions and variables reside in a shared object.
+Modular built-in functions and variables reside in a shared object.
+
+TBD.
 
 Embedding in C++
 -----------------
@@ -218,31 +255,36 @@ Changes in 0.6.0
 
 ### qse_awk_parsestd() ###
 
-In 0.5.6, it accepted a single script.
+The second parameter of qse_awk_parsestd() specifies the input script.
 
-    qse_awk_parsestd_t psin;
+In 0.5.6, it accepted a single script for input.
-    psin.type = QSE_AWK_PARSESTD_STR;
-    psin.u.str.ptr = src;
-    psin.u.str.len = qse_strlen(src);
-    qse_awk_parsestd (awk, &psin, QSE_NULL);
 
-In 0.6.X, it accepts an array of scripts.
+~~~~~{.c}
+ qse_awk_parsestd_t psin;
+ psin.type = QSE_AWK_PARSESTD_STR;
+ psin.u.str.ptr = src;
+ psin.u.str.len = qse_strlen(src);
+ qse_awk_parsestd (awk, &psin, QSE_NULL);
+~~~~~
 
-    qse_awk_parsestd_t psin[2];
+In 0.6.X, it accepts an array of scripts for input. To specify a single script,
-    psin[0].type = QSE_AWK_PARSESTD_STR;
+use an array of 2 elements whose last element is of the #QSE_AWK_PARSESTD_NULL
-    psin[0].u.str.ptr = src;
+type.
-    psin[0].u.str.len = qse_strlen(src);
+
-    psin[1].type = QSE_AWK_PARSESTD_STR;
+~~~~~{.c}
-    qse_awk_parsestd (awk, psin, QSE_NULL)
+ qse_awk_parsestd_t psin[2];
+ psin[0].type = QSE_AWK_PARSESTD_STR;
+ psin[0].u.str.ptr = src;
+ psin[0].u.str.len = qse_strlen(src);
+ psin[1].type = QSE_AWK_PARSESTD_NULL;
+ qse_awk_parsestd (awk, psin, QSE_NULL);
+~~~~~
 
 ### 0 upon Opening ###
 I/O handlers can return 0 for success upon opening.
 
 
 
-
-
-
 \skipline ---------------------------------------------------------------------
 \skipline the sample files are listed here for example list generation purpose.
 \skipline ---------------------------------------------------------------------

qse/doc/page/cenc.doc

@@ -1,13 +0,0 @@
-/** @page cenc Character Encoding
-
-@section cenc_overview Overview
-
-The library contains functions and data types for handling different character
-encodings. It uses the current system locale by default.
-
-@section cenc_cmgr qse_cmgr_t
-
-The #qse_cmgr_t type defines a simple callback interface for conversion between
-a multi-byte character and a wide character.
-
-*/

qse/doc/page/io.doc

@@ -1,8 +0,0 @@
-/** @page io I/O Handling
-
-@section io_stream Stream
-- Generic text stream interface #qse_tio_t
-- Simple text stream over a file #qse_sio_t 
-- Pipe stream to/from a process #qse_pio_t
-- Network stream to/from a remote/local host #qse_nwio_t
-*/

qse/doc/page/mainpage.md

@@ -26,6 +26,4 @@ See the subpages for more information.
 - @ref sed-cmd
 - @ref sed-embed
 - @subpage mem "Memory Management"
-- @subpage cenc "Character Encoding"
-- @subpage io  "I/O Handling"
 

qse/include/qse/awk/awk.h

@@ -978,7 +978,8 @@ struct qse_awk_rtx_ecb_t
  */
 enum qse_awk_opt_t
 {
-	QSE_AWK_TRAIT,
+	/** trait option. 0 or bitwise-ORed of ::qse_awk_trait_t values */
+	QSE_AWK_TRAIT,  
 
 	QSE_AWK_MODPREFIX,
 	QSE_AWK_MODPOSTFIX,
@@ -1001,17 +1002,14 @@ typedef enum qse_awk_opt_t qse_awk_opt_t;
  */
 enum qse_awk_trait_t
 { 
-	/**
+	/** allows undeclared variables */
-	 * allows undeclared variables and implicit concatenation 
-	 **/
 	QSE_AWK_IMPLICIT = (1 << 0),
 
-	/**
+	/** enable abort,reset,nextofile,OFILENAME,@include. */
-	 * enable abort,reset,nextofile,OFILENAME,@include.
-	 */
 	QSE_AWK_EXTRAKWS = (1 << 2),
 
-	/** supports \b getline and \b print */
+	/** supports \b getline, \b print, \b printf, \b close, \b fflush,
+	 *  piping, and file rediction */
 	QSE_AWK_RIO = (1 << 3), 
 
 	/** enables the two-way pipe if #QSE_AWK_RIO is on */
@@ -1047,11 +1045,11 @@ enum qse_awk_trait_t
 	 */
 	QSE_AWK_STRIPRECSPC = (1 << 6),
 
-	/**
+	/** strips off leading spaces when converting a string to a number. */
-	 * strips off leading spaces when converting a string to a number.
-	 */
 	QSE_AWK_STRIPSTRSPC = (1 << 7),
 
+	/** enable implicit concatenation. 
+	 *  if this is off, you need %% for concatenation.  */
 	QSE_AWK_BLANKCONCAT = (1 << 8),
 
 	/** CR + LF by default */
@@ -1606,12 +1604,24 @@ QSE_EXPORT void qse_awk_seterror (
 	const qse_awk_loc_t* errloc  /**< error location */
 );
 
+/**
+ * The qse_awk_getopt() function gets the value of an option
+ * specified by \a id into the buffer pointed to by \a value.
+ *
+ * \return 0 on success, -1 on failure
+ */
 QSE_EXPORT int qse_awk_getopt (
 	qse_awk_t*    awk,
 	qse_awk_opt_t id,
 	void*         value
 );
 
+/**
+ * The qse_awk_setopt() function sets the value of an option 
+ * specified by \a id to the value pointed to by \a value.
+ *
+ * \return 0 on success, -1 on failure
+ */
 QSE_EXPORT int qse_awk_setopt (
 	qse_awk_t*    awk,
 	qse_awk_opt_t id,
@@ -2243,6 +2253,7 @@ QSE_EXPORT qse_awk_val_t* qse_awk_rtx_makenilval (
 
 /**
  * The qse_awk_rtx_makeintval() function creates an integer value.
+ * If \a v is one of -1, 0, 1, this function never fails.
  * \return value on success, #QSE_NULL on failure
  */
 QSE_EXPORT qse_awk_val_t* qse_awk_rtx_makeintval (

qse/include/qse/sed/sed.h

@@ -451,7 +451,7 @@ QSE_EXPORT void* qse_sed_getxtn (
  * specified by \a id into the buffer pointed to by \a value.
  *
  * The \a value field is dependent on \a id:
- *  - #QSE_SED_TRAIT - int*
+ *  - #QSE_SED_TRAIT - int*, 0 or bitwised-ORed of #qse_sed_trait_t values
  *  - #QSE_SED_TRACER - qse_sed_tracer_t*
  *  - #QSE_SED_LFORMATTER - qse_sed_lformatter_t*
  *
@@ -468,7 +468,7 @@ QSE_EXPORT int qse_sed_getopt (
  * specified by \a id to the value pointed to by \a value.
  *
  * The \a value field is dependent on \a id:
- *  - #QSE_SED_TRAIT - const int*
+ *  - #QSE_SED_TRAIT - const int*, 0 or bitwised-ORed of #qse_sed_trait_t values
  *  - #QSE_SED_TRACER - qse_sed_tracer_t
  *  - #QSE_SED_LFORMATTER - qse_sed_lformatter_t
  *

qse/samples/awk/awk10.c

@@ -149,4 +149,3 @@ int qse_main (int argc, qse_achar_t* argv[])
 	init_awk_sample_locale ();
 	return qse_runmain (argc, argv, awk_main);
 }
-