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.

The following code fragment illustrates the basic steps of embedding the processor.

{{{
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.
)))

A set of primitive functions should be provided by the caller to create an instance of the processor as the library aims to be system indepenent. 

{{{
typedef void* (*ase_malloc_t)  (void* custom, ase_size_t n);
typedef void* (*ase_realloc_t) (void* custom, void* ptr, ase_size_t n);
typedef void  (*ase_free_t)    (void* custom, void* ptr);

typedef ase_bool_t (*ase_isccls_t) (void* custom, ase_cint_t c);
typedef ase_cint_t (*ase_toccls_t) (void* custom, ase_cint_t c);

struct ase_mmgr_t
{
	ase_malloc_t  malloc;
	ase_realloc_t realloc;
	ase_free_t    free;
	void*         custom_data;
};

struct ase_ccls_t
{
	ase_isccls_t is_upper;
	ase_isccls_t is_lower;
	ase_isccls_t is_alpha;
	ase_isccls_t is_digit;
	ase_isccls_t is_xdigit;
	ase_isccls_t is_alnum;
	ase_isccls_t is_space;
	ase_isccls_t is_print;
	ase_isccls_t is_graph;
	ase_isccls_t is_cntrl;
	ase_isccls_t is_punct;
	ase_toccls_t to_upper;
	ase_toccls_t to_lower;
	void*        custom_data;
};

struct ase_awk_prmfns_t
{
	ase_mmgr_t mmgr;
	ase_ccls_t ccls;

	struct
	{
		ase_awk_pow_t     pow;
		ase_awk_sprintf_t sprintf;
		ase_awk_aprintf_t aprintf;
		ase_awk_dprintf_t dprintf;
		ase_awk_abort_t   abort;
		void*             custom_data;
	} misc;
};

The primitive functions handle memory allocation, charater classes, and 

=== 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}
]]]