diff --git a/qse/doc/Makefile.am b/qse/doc/Makefile.am index 5fcdf6fa..054537b1 100644 --- a/qse/doc/Makefile.am +++ b/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 \ diff --git a/qse/doc/Makefile.in b/qse/doc/Makefile.in index e2906db6..51c24e26 100644 --- a/qse/doc/Makefile.in +++ b/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 \ diff --git a/qse/doc/page/awk-embed.md b/qse/doc/page/awk-embed.md index 9f6fddc3..69b9d108 100644 --- a/qse/doc/page/awk-embed.md +++ b/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 -a map value with qse_awk_rtx_makemapval() or qse_awk_rtx_makemapvalwithdata(). -The sample below demonstrates how to use qse_awk_rtx_makemapvalwithdata(), -pass a created map value to qse_awk_rtx_call(), and traverse a map value -returned with qse_awk_rtx_getfirstmapvalitr() and qse_awk_rtx_getnextmapvalitr(). +Similarly, you can pass a more complex value than a plain number or string. +You can compose a map value with qse_awk_rtx_makemapval() or +qse_awk_rtx_makemapvalwithdata(). The following sample demonstrates how to +use qse_awk_rtx_makemapvalwithdata(), pass a created map value to +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 -built-in function with qse_awk_addfnc(). The following sample shows how to add -a function named *basename* that get the base file name part of a path name. +QSEAWK predefines built-in functions like *match* and *gsub*. You can add your +own built-in function with qse_awk_addfnc(). The following sample shows how to +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; - 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.5.6, it accepted a single script for input. -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]; - 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_STR; - qse_awk_parsestd (awk, psin, QSE_NULL) +In 0.6.X, it accepts an array of scripts for input. To specify a single script, +use an array of 2 elements whose last element is of the #QSE_AWK_PARSESTD_NULL +type. + +~~~~~{.c} + 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 --------------------------------------------------------------------- diff --git a/qse/doc/page/cenc.doc b/qse/doc/page/cenc.doc deleted file mode 100644 index c12afab7..00000000 --- a/qse/doc/page/cenc.doc +++ /dev/null @@ -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. - -*/ diff --git a/qse/doc/page/io.doc b/qse/doc/page/io.doc deleted file mode 100644 index 6429f249..00000000 --- a/qse/doc/page/io.doc +++ /dev/null @@ -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 -*/ diff --git a/qse/doc/page/mainpage.md b/qse/doc/page/mainpage.md index e1b26e81..fefaa2a2 100644 --- a/qse/doc/page/mainpage.md +++ b/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" diff --git a/qse/include/qse/awk/awk.h b/qse/include/qse/awk/awk.h index 81d79b6d..8f73f344 100644 --- a/qse/include/qse/awk/awk.h +++ b/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 and implicit concatenation - **/ + /** allows undeclared variables */ 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 ( diff --git a/qse/include/qse/sed/sed.h b/qse/include/qse/sed/sed.h index 72c8a660..701a403c 100644 --- a/qse/include/qse/sed/sed.h +++ b/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 * diff --git a/qse/samples/awk/awk10.c b/qse/samples/awk/awk10.c index 6b2d8dd1..b08c6b1d 100644 --- a/qse/samples/awk/awk10.c +++ b/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); } -