qse/ase/doc/awk-en.man

.title ASEAWK

== ASEAWK ==
ASE provides an embeddable processor of a dialect of the AWK programming language. The language implemented is slightly different from {the version developed by Brian W. Kernighan, http://cm.bell-labs.com/cm/cs/awkbook/index.html} and has been adjusted to the author's preference.

Embedding a processor requires the following basic steps.

[[[
* Create a processor instance
* Parse an AWK script
* Run the script parsed
* Destroy the instance
]]]

The following code fragment illustrates the basic steps.

{{{
1) #include <ase/awk/awk.h>

2) ase_awk_t* awk;
3) awk = ase_awk_open (...);
4) if (ase_awk_parse (awk, ...) == -1)
   {
        /* parse error */
   }
   else
   {
5)     if (ase_awk_run (awk, ...) == -1)
       {
           /* run-time error */
       }
   }
6)  ase_awk_close (awk);
}}}

(((
* Most of the functions and data types needed are defined in the header file <ase/awk/awk.h>. 
* ase_awk_t represents the processor. However, the internal representation is not exposed.
* ase_awk_open creates the processor instance.
* ase_awk_parse parses an AWK script.
* ase_awk_run executes the script parsed.
* ase_awk_close destroys the processor instance.
)))

=== Primitive Functions ===

ase_awk_open requires a set of primitive functions to be passed. This set include pointers to the system primitive functions for system dependent operation such as memory allocation, string formatting, etc.

=== Source IO Handler ===

ase_awk_srcio_t

The source code is read in with the source input handler provided. 
The optional source output handler writes the generated source code.

=== External IO Handler ===

ase_awk_extio_t
External IO handlers should be provided to support the AWK's built-in IO facilities.

=== Reference Manual ===
[[[
* {Reference Manual,awk-ref-en.html}
]]]