hyung-hwan/qse
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated docs

Browse Source
This commit is contained in:
hyung-hwan 2013-01-15 08:11:25 +00:00
parent 3d1c8b3893
commit 8160249b38
9 changed files with 98 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
qse/doc/Makefile.am
View File

@ -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 \

2
qse/doc/Makefile.in
View File

@ -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 \

106
qse/doc/page/awk-embed.md
View File

@ -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 ---------------------------------------------------------------------

13
qse/doc/page/cenc.doc
View File

@ -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.
*/

8
qse/doc/page/io.doc
View File

@ -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
*/

2
qse/doc/page/mainpage.md
View File

@ -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"

31
qse/include/qse/awk/awk.h
View File

@ -978,6 +978,7 @@ struct qse_awk_rtx_ecb_t
*/
enum qse_awk_opt_t
{
/** trait option. 0 or bitwise-ORed of ::qse_awk_trait_t values */
QSE_AWK_TRAIT,
QSE_AWK_MODPREFIX,
@ -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 (

4
qse/include/qse/sed/sed.h
View File

@ -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
*

1
qse/samples/awk/awk10.c
View File

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