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

updated documentation

Browse Source
This commit is contained in:
hyung-hwan
2013-01-09 08:03:21 +00:00
parent 19b4e697af
commit 6e94d324ef
20 changed files with 1143 additions and 1317 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -62,23 +62,31 @@ functions like *gsub* or *index*.
\includelineno awk03.c
If you want to pass arguments to the function you call with qse_awk_rtx_call(),
you must create values with value creation functions, updates their reference
count, and pass them to qse_awk_rtx_call(). The sample below creates 2 integer
values with qse_awk_rtx_makeintval() and pass them to the *pow* function.
If you want to pass arguments to the function, you must create values with
value creation functions, updates their reference count, and pass them to
qse_awk_rtx_call(). The sample below creates 2 integer values with
qse_awk_rtx_makeintval() and pass them to the *pow* function.
\includelineno awk04.c
While qse_awk_rtx_call() looks up a function in the function table by name,
you can find the function in advance and use the information found when
calling a function. qse_awk_rtx_findfun() and qse_awk_rtx_callfun() come
to play a role in this situation. qse_awk_rtx_call() in the sample above
can be translated into 2 separate calls to qse_awk_rtx_findfun() and
qse_awk_rtx_callfun(). You can reduce look-up overhead via these 2
functions if you have to execute the same function multiple times.
calling it. qse_awk_rtx_findfun() and qse_awk_rtx_callfun() come to play a role
in this situation. qse_awk_rtx_call() in the sample above can be translated
into 2 separate calls to qse_awk_rtx_findfun() and qse_awk_rtx_callfun().
You can reduce look-up overhead via these 2 functions if you are to execute
the same function multiple times.
\includelineno awk05.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().
\includelineno awk06.c
Global Variables
----------------
@ -91,6 +99,29 @@ Built-in Functions
You can add built-in functions with qse_awk_addfnc().
On the other hand, modular built-in functions reside in a shared object.
Single Script over Multiple Data Streams
----------------------------------------
Customizing Language Features
-----------------------------
Creating multiple awk objects
-----------------------------
Memory Pool
-----------
Embedding in C++
-----------------
The QSE::Awk class and QSE::StdAwk classe wrap the underlying C library routines
for better object-orientation. These two classes are defined in <qse/awk/Awk.hpp>
and <qse/awk/StdAwk.hpp> respectively. The embedding task can be simplified despite
slight performance overhead. The hello-world sample in C can be rewritten with
less numbers of lines in C++.
\includelineno awk21.cpp
Changes in 0.6.0
----------------

180
qse/doc/page/awk.doc
View File

@ -1,180 +0,0 @@
/** @page awk AWK
@section awk-content CONTENTS
- @ref awk-intro "INTRODUCTION"
@section awk-intro INTRODUCTION
QSEAWK is an AWK interpreter and is a part of the @ref qse_intro "QSE" library.
Its design focuses on building a flexible and robust embedding API with minimal
platform dependency. An embedding application is capable of:
- adding new global variables and functions.
- getting and set the value of a global variable.
- calling a function with or without parameters and getting its return value.
- customizing I/O handlers for file, pipe, console I/O.
- creating multiple interpreters independent of each other.
- running a single script with different I/O streams independently.
- changing language features by setting options.
- and more
The library implements AWK in multiple levels:
- base interpreter
- standard interpreter
- parallel interpreter
The base interpreter provides most core language features while minimizing
platform dependence. When working with the base interpreter, you're required
to write primtive operation handlers like I/O and pass them in to make it
useful. The standard interpreter is usable immediately since it implements
all the primitive operations required by the base interpreter and adds
standard AWK functions. The parallel interpreter enables parallel processing
by adding various MPI variables and functions to the standard interpreter.
Embedding a standard interpreter typically involves the following steps.
- open a new interpreter
- parse in a source script
- open a new runtime context
- execute pattern-action blocks or call a function
- close the runtime context
- close the interpter
The code example below demonstrates the steps in C. It executes the one liner
<b>BEGIN { print "hello, world" }</b>.
@code
/* cc -o hello hello.c -lqseawk -lqsecmn -lm */
#include <qse/awk/std.h>
#include <qse/cmn/stdio.h>
#define FAIL(msg) do { qse_printf(QSE_T("ERR: %s\n"),msg); goto oops; } while(0)
int main ()
{
qse_awk_t* awk = QSE_NULL;
qse_awk_rtx_t* rtx = QSE_NULL;
qse_awk_val_t* retv;
qse_awk_parsestd_t psin;
int ret = -1;
awk = qse_awk_openstd (0); /* open a new interpreter */
if (!awk) FAIL ("cannot open awk");
/* parse the hello world script from a string */
psin.type = QSE_AWK_PARSESTD_STR;
psin.u.str.ptr = QSE_T("BEGIN { print \"hello, world\" }");
psin.u.str.len = qse_strlen(psin.u.str.ptr);
if (qse_awk_parsestd (awk, &psin, QSE_NULL) <= -1)
FAIL (qse_awk_geterrmsg(awk));
rtx = qse_awk_rtx_openstd ( /* open a runtime context */
awk, 0, /* no extension */
QSE_T("hello"), /* ARGV[0] */
QSE_NULL, /* stdin */
QSE_NULL, /* stdout */
QSE_NULL /* default cmgr */
);
if (!rtx) FAIL (qse_awk_geterrmsg(awk));
/* exeucte pattern-action blocks */
retv = qse_awk_rtx_loop (rtx);
if (!retv) FAIL (qse_awk_rtx_geterrmsg(rtx));
qse_awk_rtx_refdownval (rtx, retv); /* destroy the return value */
ret = 0;
oops:
if (rtx) qse_awk_rtx_close (rtx); /* close the runtime context */
if (awk) qse_awk_close (awk); /* close the interpreter */
return ret;
}
@endcode
Things can get simpler when you use C++ API. Note that the C++ API supports
1 single runtime context for each interpreter.
@code
/* c++ -o hello hello.cpp -lqseawkxx -lqseawk -lqsecmnxx -lqsecmn -lm */
#include <qse/awk/StdAwk.hpp>
#include <iostream>
#ifdef QSE_CHAR_IS_MCHAR
# define xcout std::cout
#else
# define xcout std::wcout
#endif
struct MyAwk: public QSE::StdAwk { ~MyAwk () { QSE::StdAwk::close (); } };
#define FAIL(awk) do { \
xcout << QSE_T("ERR: ") << awk.getErrorMessage() << std::endl; \
return -1; \
} while (0)
int main (int argc, char* argv[])
{
MyAwk awk;
// open a new interpreter
if (awk.open () <= -1) FAIL (awk);
// set ARGV[0]
if (awk.addArgument (QSE_T("hello")) <= -1) FAIL (awk);
// parse the source script string
MyAwk::SourceString in(QSE_T("BEGIN { print \"hello, world\" }"));
if (awk.parse (in, MyAwk::Source::NONE) == QSE_NULL) FAIL (awk);
// execute pattern-action blocks.
MyAwk::Value r;
if (awk.loop (&r) <= -1) FAIL (awk);
return 0;
}
@endcode
This library also provides a stand-alone AWK interpreter that you can use
in a console environment. The source code is located under the
<project-root>/cmd/awk subdirectory. See the usage below.
@code
$ qseawk
USAGE: qseawk [options] -f sourcefile [ -- ] [datafile]*
qseawk [options] [ -- ] sourcestring [datafile]*
Where options are:
-h/--help print this message
--version print version
-D show extra information
-c/--call name call a function instead of entering
the pattern-action loop
-f/--file sourcefile set the source script file
-d/--deparsed-file deparsedfile set the deparsing output file
-F/--field-separator string set a field separator(FS)
-v/--assign var=value add a global variable with a value
-m/--memory-limit number limit the memory usage (bytes)
-X number fail the number'th memory allocation
--script-encoding string specify script file encoding name
--console-encoding string specify console encoding name
--implicit on/off allow undeclared variables
--explicit on/off allow declared variables(local,global)
--extraops on/off enable extra operators(<<,>>,^^,\)
--rio on/off enable builtin I/O including getline & print
--rwpipe on/off allow a dual-directional pipe
--newline on/off enable a newline to terminate a statement
--striprecspc on/off strip spaces in splitting a record
--stripstrspc on/off strip spaces in converting a string to a number
--nextofile on/off enable 'nextofile'
--reset on/off enable 'reset'
--crlf on/off use CRLF for a newline
--maptovar on/off allow a map to be assigned or returned
--pablock on/off enable pattern-action loop
--rexbound on/off enable {n,m} in a regular expression
--ncmponstr on/off perform numeric comparsion on numeric strings
--strictnaming on/off enable the strict naming rule
--include on/off enable '@include'
--tolerant on/off make more I/O fault-tolerant
--abort on/off enable 'abort'
@endcode
*/

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

@ -13,7 +13,7 @@ aspects of embedding application and an embedded object from each other.
The library is licensed under the GNU Lesser General Public License version 3:
http://www.gnu.org/licenses/
The project webpage: http://code.abiyo.net/@qse
The project webpage: http://code.abiyo.net/@qse or http://qse.googlecode.com
For further information, contact:
Chung, Hyung-Hwan <hyunghwan.chung@gmail.com>
@ -21,11 +21,10 @@ Chung, Hyung-Hwan <hyunghwan.chung@gmail.com>
See the subpages for more information.
- @ref installation
- @ref awk-lang
- @ref awk-embed
- @subpage mem "Memory Management"
- @subpage cenc "Character Encoding"
- @subpage io "I/O Handling"
- @subpage awk "AWK Interpreter"
- @subpage sed "SED Stream Editor"
- @subpage awk-lang
- @subpage awk-embed