Recovered from cvs revision 2007-05-01 07:40:00

ase/doc/ase-en.man

@@ -0,0 +1,30 @@
+.title ASE
+
+= ASE =
+
+ASE is a programming library implementing various programming languages and text utilities for embedding purposes. The library is developed in the C programming language and provides the JNI binding to JAVA and the COM interface.
+
+(Warning: This page is only for the test purpose prior to proper release and the contents can be changed anytime without prior notice.)
+
+== Download ==
+
+Download the library source code from the following links.
+
+ase-0.1.0.tgz
+[[[
+* {Link 1,ase-0.1.0.tgz}
+* Link 2
+]]]
+
+== Documentation ==
+
+[[[
+* {Quickstart,quickstart-en.html}
+* {AWK Embedder's guide,awk-en.html}
+* {LISP Embedder's guide,lsp-en.html}
+* {Frequently Asked Questions,faq-en.html}
+]]]
+
+== Licensing ==
+
+ASE is distributed under a {BSD license,license.html} and is free for all uses.

ase/doc/ase-ko.man

@@ -0,0 +1,29 @@
+.title ASE
+
+= ASE =
+
+ASE는 임베딩을 목적으로 여러가지 프로그래밍언어를 구현하는 라이브러리이다. C언어로 개발되며 자바 JNI인터페이스와 COM인터페이스를 제공한다.
+
+(경고: 본 페이지는 정식 배포전에 시험용으로 제작된것이므로, 언제든지 내용이 변경될 수 있다.)
+
+== Download ==
+
+다음 링크에서 소스코드를 받을수 있다.
+
+ase-0.1.0.tgz
+[[[
+* {링크 1,ase-0.1.0.tgz}
+* 링크 2
+]]]
+
+== Documentation ==
+
+[[[
+* {초간단가이드,quickstart-ko.html}
+* {사용자가이드,awk-en.html}
+* {자주받는질문,faq-ko.html}
+]]]
+
+== Licensing ==
+
+ASE는 {BSD 라이센스,license.html}하에 무료로 배포된다. 단 {라이센스,license.html}는 번역상에 발생할수 있는 문제를 최소화하기 위해 영문으로만 제공된다.

ase/doc/awk-en.man

@@ -0,0 +1,202 @@
+.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.
+
+== Overview ==
+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.
+)))
+
+More detailed description is available {here,awk-mini-en.html}. You may refer to other sample files such as [[ase/test/awk/awk.c]] and [[ase/awk/jni.c]].
+
+== Primitive Functions ==
+A set of primitive functions is needed to create an instance of the AWK processor. A primitive function is a user-defined function to help the library perform system-dependent operations such as memory allocation, character class handling.
+
+{{{
+typedef struct ase_awk_prmfns_t ase_awk_prmfns_t;
+
+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_dprintf_t dprintf;
+        void*             custom_data;
+    } misc;
+};
+}}}
+
+A caller of [[ase_awk_open]] should fill in most of the fields of a [[ase_awk_prmfns_t]] structure and pass the structure to it. The function pointers in the miscellaneous group labeled [misc] is defined as follows:
+
+{{{
+/* returns the value of x raised to the power of y */
+typedef ase_real_t (*ase_awk_pow_t) (void* custom, ase_real_t x, ase_real_t y);
+
+/* similar to snprintf of the standard C library. */
+typedef int (*ase_awk_sprintf_t) (void* custom, ase_char_t* buf, ase_size_t size, const ase_char_t* fmt, ...);
+
+/* similar to printf of the standard C library. called by a few uncommonly 
+ * used output functions usually for debugging purpose */
+typedef void (*ase_awk_dprintf_t) (void* custom, const ase_char_t* fmt, ...); 
+}}}
+
+The fourth field of the group is passed to its member functions as the first argument on invocation. The function pointed by the [[sprintf]] field should ensure that the resuliting string is null-terminated and [[%s]] and [[%c]] are accepted for the [[ase_char_t*]] and [[ase_char_t]] type respectively regardless the character mode.
+
+The memory manager group labeled [mmgr] and the character class group labled [ccls] are defined as follows:
+
+{{{
+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;
+};
+}}}
+
+The functions in these groups perform the memory operations and character class related operations respectively. They follow the style of the memory allocation functions and character class handling functions of the standard C library except that they accept a pointer to the user-defined data as the first argument, thus providing more flexibility. The pointer to the user-defined data is specified into the [[custom_data]] field of each group. The [[realloc]] field, however, can be [[ASE_NULL]], in which case the functions pointed by the free and the malloc field replace the role of the function pointed by the [[realloc]] field. 
+
+== Source IO Handler ==
+
+The source code is handled by a source input handler provided by the user. The optional source code output handler can be provided to have the internal parse tree converted back to the source code.
+
+The source code handler is defined as follows:
+
+{{{
+typedef ase_ssize_t (*ase_awk_io_t) (int cmd, void* custom, ase_char_t* data, ase_size_t count);
+
+typedef struct ase_awk_srcios_t ase_awk_srcios_t;
+
+struct ase_awk_srcios_t
+{
+    ase_awk_io_t in; /* source input */
+    ase_awk_io_t out; /* source output */
+    void*        custom_data;
+};
+}}}
+
+The [[in]] field of the ase_awk_srcios_t is mandatory and should be filled in. The [[out]] field can be set to [[ASE_NULL]] or can point to a source output handling function. The [[custom_data]] field is passed to the source handlers as the second argument. The first parameter [[cmd]] of the source input handler is one of [[ASE_AWK_IO_OPEN]], [[ASE_AWK_IO_CLOSE]], [[ASE_AWK_IO_READ]]. The first parameter [[cmd]] of the source output handler is one of [[ASE_AWK_IO_OPEN]], [[ASE_AWK_IO_CLOSE]], [[ASE_AWK_IO_WRITE]]. The third parameter [[data]] and the fourth parameter [[count]] are the pointer to the buffer to read data into and its size if the first parameter [[cmd]] is [[ASE_AWK_IO_READ]] while they are the pointer to the data and its size if [[cmd]] is [[ASE_AWK_IO_WRITE]].
+
+The source handler should return a negative value for an error and zero or a positive value otherwise. However, there is a subtle difference in the meaning of the return value depending on the value of the first parameter [[cmd]].
+
+When [[cmd]] is [[ASE_AWK_IO_OPEN]], the return value of -1 and 1 indicates the failure and the success respectively. In addition, the return value of 0 indicates that the operation is successful but has reached the end of the stream. The library calls the handler with [[ASE_AWK_IO_CLOSE]] for deinitialization if the return value is 0 or 1. When [[cmd]] is [[ASE_AWK_IO_CLOSE]], the return value of -1 and 0 indicate the failure and the success respectively. When [[cmd]] is [[ASE_AWK_IO_READ]] or [[ASE_AWK_IO_WRITE]], the return value of -1 indicates the failure, 0 the end of the stream, and other positive values the number of characters read or written.
+
+The typical source handler will look as follows:
+{{{
+ase_ssize_t awk_srcio_in (int cmd, void* arg, ase_char_t* data, ase_size_t size)
+{
+    if (cmd == ASE_AWK_IO_OPEN)
+    {
+        /* open the stream */
+        return 1;
+    }
+    else if (cmd == ASE_AWK_IO_CLOSE)
+    {
+        /* close the stream */
+        return 0;
+    }
+    else if (cmd == ASE_AWK_IO_READ)
+    {
+        /* read the stream */
+        return the number of characters read;
+    }
+
+    return -1;
+}
+
+ase_ssize_t awk_srcio_out (int cmd, void* arg, ase_char_t* data, ase_size_t size)
+{
+    if (cmd == ASE_AWK_IO_OPEN) 
+    {
+    /* open the stream */
+        return 1;
+    }
+    else if (cmd == ASE_AWK_IO_CLOSE)
+    {
+        /* close the stream after flushing it */
+        return 0;
+    }
+    else if (cmd == ASE_AWK_IO_WRITE)
+    {
+        /* write the stream */
+        return the number of characters written;
+    }
+
+    return -1;
+}
+}}}
+
+Once you have the source handler ready, you can fill in the fields of a [[ase_awk_srcios_t]] structure and pass it to the call of [[ase_awk_parse]].
+
+{{{
+ase_awk_srcios_t srcios;
+
+srcios.in = awk_srcio_in;
+srcios.out = awk_srcio_out;
+srcios.custom_data = point to the extra information necessary; 
+
+if (ase_awk_parse (awk, &srcios) == -1)
+{
+	/* handle error */
+}
+}}}
+
+== External IO Handler ==
+
+External IO handlers should be provided to support the AWK's built-in IO facilities.

ase/doc/awk-mini-en.man

@@ -0,0 +1,458 @@
+.title Annotated ASEAWK Embedding Sample
+
+= Annotated ASEAWK Embedding Sample =
+
+This document annotates a simple embedding sample code [[ase/test/awk/mini.c]]. Locate the [[ase_main]] function to begin exploring the sample.
+
+== mini.c ==
+
+{{{
+#include <ase/awk/awk.h>
+#include <ase/cmn/str.h>
+#include <ase/cmn/mem.h>
+
+#include <ase/utl/ctype.h>
+#include <ase/utl/stdio.h>
+#include <ase/utl/main.h>
+
+#include <stdarg.h>
+#include <math.h>
+#include <stdlib.h>
+}}}
+
+Most of the data types and functions needed to embed a AWK processor is defined in [[ase/awk/awk.h]]. Other headers files are included as this sample code uses functions from them.
+
+{{{
+struct awk_src_io
+{
+	const ase_char_t* file;
+	FILE* handle;
+};
+
+static const ase_char_t* data_file = ASE_NULL;
+
+#if defined(vms) || defined(__vms)
+/* it seems that the main function should be placed in the main object file
+ * in OpenVMS. otherwise, the first function in the main object file seems
+ * to become the main function resulting in program start-up failure. */
+#include <ase/utl/main.c>
+#endif
+
+#ifndef NDEBUG
+void ase_assert_abort (void)
+{
+	abort ();
+}
+
+void ase_assert_printf (const ase_char_t* fmt, ...)
+{
+	va_list ap;
+	va_start (ap, fmt);
+	ase_vprintf (fmt, ap);
+	va_end (ap);
+}
+#endif
+}}}
+
+The library requires [[ase_assert_abort]] and [[ase_assert_printf]] to be defined to support the assertion statements [[ASE_ASSERT]] and [[ASE_ASSERTX]] defined in [[ase/cmn/macros.h]] when [[NDEBUG]] is not defined. [[ASE_ASSERT]] behaves the same as the standard [[assert]] statement while an additional textual description can be passed to [[ASE_ASSERTX]]. They are all usuable in the caller program as well.
+
+{{{
+void* awk_malloc  (void* custom, ase_size_t n)            { return malloc (n); }
+void* awk_realloc (void* custom, void* ptr, ase_size_t n) { return realloc (ptr, n); }
+void  awk_free    (void* custom, void* ptr)               { free (ptr); }
+}}}
+
+The memory management functions are required by the library. They need to form a part of the [[ase_awk_prmfns_t]] structure and be passed to [[ase_awk_open]]. Each function looks after the counterpart in the standard C library except that the first parameter to each function is a pointer to a custom data provided by the caller. 
+
+{{{
+ase_bool_t awk_isupper  (void* custom, ase_cint_t c) { return ase_isupper (c); }
+ase_bool_t awk_islower  (void* custom, ase_cint_t c) { return ase_islower (c); }
+ase_bool_t awk_isalpha  (void* custom, ase_cint_t c) { return ase_isalpha (c); }
+ase_bool_t awk_isdigit  (void* custom, ase_cint_t c) { return ase_isdigit (c); }
+ase_bool_t awk_isxdigit (void* custom, ase_cint_t c) { return ase_isxdigit (c); }
+ase_bool_t awk_isalnum  (void* custom, ase_cint_t c) { return ase_isalnum (c); }
+ase_bool_t awk_isspace  (void* custom, ase_cint_t c) { return ase_isspace (c); }
+ase_bool_t awk_isprint  (void* custom, ase_cint_t c) { return ase_isprint (c); }
+ase_bool_t awk_isgraph  (void* custom, ase_cint_t c) { return ase_isgraph (c); }
+ase_bool_t awk_iscntrl  (void* custom, ase_cint_t c) { return ase_iscntrl (c); }
+ase_bool_t awk_ispunct  (void* custom, ase_cint_t c) { return ase_ispunct (c); }
+ase_cint_t awk_toupper  (void* custom, ase_cint_t c) { return ase_toupper (c); }
+ase_cint_t awk_tolower  (void* custom, ase_cint_t c) { return ase_tolower (c); }
+}}}
+
+The character class handling functions must be provided by the caller. Like the memory management functions, they form a part of the [[ase_awk_prmfns_t]] structure and passwd to [[ase_awk_open]].
+
+{{{
+ase_real_t awk_pow (void* custom, ase_real_t x, ase_real_t y) 
+{
+	return pow (x, y); 
+}
+
+int awk_sprintf (void* custom, ase_char_t* buf, ase_size_t size, const ase_char_t* fmt, ...)
+{
+	int n;
+
+	va_list ap;
+	va_start (ap, fmt);
+	n = ase_vsprintf (buf, size, fmt, ap);
+	va_end (ap);
+
+	return n;
+}
+
+void awk_dprintf (void* custom, const ase_char_t* fmt, ...)
+{
+	va_list ap;
+	va_start (ap, fmt);
+	ase_vfprintf (stderr, fmt, ap);
+	va_end (ap);
+}
+}}}
+
+The [[awk_pow]] function returns the value of the second parameter [[x]] raised to the third parameter [[y]]. The [[awk_sprintf]] function is similar to the standard [[snprintf]] to the standard [[snprintf]]. It should make sure that the buffer [[buf]] is null-terminated if the size [[size]] is greater than 0. Refer to [[ase_sprintf]] in [[ase/utl/stdio.h]] for details. The [[awk_dprintf]] fucntion is similar to [[fprintf(stderr,...)]] is called when the text output is performed for debugging purpose.
+
+{{{
+ase_ssize_t awk_srcio_in (int cmd, void* arg, ase_char_t* data, ase_size_t size)
+{
+	struct awk_src_io* src_io = (struct awk_src_io*)arg;
+	ase_cint_t c;
+
+	if (cmd == ASE_AWK_IO_OPEN)
+	{
+		if (src_io->file == ASE_NULL) return 0;
+		src_io->handle = ase_fopen (src_io->file, ASE_T("r"));
+		if (src_io->handle == NULL) return -1;
+		return 1;
+	}
+	else if (cmd == ASE_AWK_IO_CLOSE)
+	{
+		if (src_io->file == ASE_NULL) return 0;
+		fclose ((FILE*)src_io->handle);
+		return 0;
+	}
+	else if (cmd == ASE_AWK_IO_READ)
+	{
+		if (size <= 0) return -1;
+		c = ase_fgetc ((FILE*)src_io->handle);
+		if (c == ASE_CHAR_EOF) return 0;
+		*data = (ase_char_t)c;
+		return 1;
+	}
+
+	return -1;
+}
+}}}
+
+The source code is read in by the source code input handler as specified in the [[in]] field of the [[ase_awk_srcios_t]] structure passed to the [[ase_awk_parse]] function. This sample, however, doesn't use the source output handler which is used to show the internal parse tree. 
+
+{{{
+/* external i/o handler for pipe */
+ase_ssize_t awk_extio_pipe (int cmd, void* arg, ase_char_t* data, ase_size_t size)
+{
+	ase_awk_extio_t* epa = (ase_awk_extio_t*)arg;
+
+	switch (cmd)
+	{
+		case ASE_AWK_IO_OPEN:
+		{
+			FILE* handle;
+			const ase_char_t* mode;
+
+			if (epa->mode == ASE_AWK_EXTIO_PIPE_READ)
+				mode = ASE_T("r");
+			else if (epa->mode == ASE_AWK_EXTIO_PIPE_WRITE)
+				mode = ASE_T("w");
+			else return -1;
+
+			handle = ase_popen (epa->name, mode);
+			if (handle == NULL) return -1;
+			epa->handle = (void*)handle;
+			return 1;
+		}
+
+		case ASE_AWK_IO_CLOSE:
+		{
+			fclose ((FILE*)epa->handle);
+			epa->handle = NULL;
+			return 0;
+		}
+
+		case ASE_AWK_IO_READ:
+		{
+			if (ase_fgets (data, size, (FILE*)epa->handle) == ASE_NULL) 
+			{
+				if (ferror((FILE*)epa->handle)) return -1;
+				return 0;
+			}
+			return ase_strlen(data);
+		}
+
+		case ASE_AWK_IO_WRITE:
+		{
+		#if defined(ASE_CHAR_IS_WCHAR) && defined(__linux)
+			/* fwprintf seems to return an error with the file
+			 * pointer opened by popen, as of this writing. 
+			 * anyway, hopefully the following replacement 
+			 * will work all the way. */
+			int n = fprintf (
+				(FILE*)epa->handle, "%.*ls", size, data);
+		#else
+			int n = ase_fprintf (
+				(FILE*)epa->handle, ASE_T("%.*s"), size, data);
+		#endif
+			if (n < 0) return -1;
+
+			return size;
+		}
+
+		case ASE_AWK_IO_FLUSH:
+		{
+			if (epa->mode == ASE_AWK_EXTIO_PIPE_READ) return -1;
+			else return 0;
+		}
+
+		case ASE_AWK_IO_NEXT:
+		{
+			return -1;
+		}
+	}
+
+	return -1;
+}
+
+/* external i/o handler for file */
+ase_ssize_t awk_extio_file (int cmd, void* arg, ase_char_t* data, ase_size_t size)
+{
+	ase_awk_extio_t* epa = (ase_awk_extio_t*)arg;
+
+	switch (cmd)
+	{
+		case ASE_AWK_IO_OPEN:
+		{
+			FILE* handle;
+			const ase_char_t* mode;
+
+			if (epa->mode == ASE_AWK_EXTIO_FILE_READ)
+				mode = ASE_T("r");
+			else if (epa->mode == ASE_AWK_EXTIO_FILE_WRITE)
+				mode = ASE_T("w");
+			else if (epa->mode == ASE_AWK_EXTIO_FILE_APPEND)
+				mode = ASE_T("a");
+			else return -1;
+
+			handle = ase_fopen (epa->name, mode);
+			if (handle == NULL) return -1;
+
+			epa->handle = (void*)handle;
+			return 1;
+		}
+
+		case ASE_AWK_IO_CLOSE:
+		{
+			fclose ((FILE*)epa->handle);
+			epa->handle = NULL;
+			return 0;
+		}
+
+		case ASE_AWK_IO_READ:
+		{
+			if (ase_fgets (data, size, (FILE*)epa->handle) == ASE_NULL) 
+			{
+				if (ferror((FILE*)epa->handle)) return -1;
+				return 0;
+			}
+			return ase_strlen(data);
+		}
+
+		case ASE_AWK_IO_WRITE:
+		{
+			int n = ase_fprintf (
+				(FILE*)epa->handle, ASE_T("%.*s"), size, data);
+			if (n < 0) return -1;
+
+			return size;
+		}
+
+		case ASE_AWK_IO_FLUSH:
+		{
+			if (fflush ((FILE*)epa->handle) == EOF) return -1;
+			return 0;
+		}
+
+		case ASE_AWK_IO_NEXT:
+		{
+			return -1;
+		}
+
+	}
+
+	return -1;
+}
+
+/* external i/o handler for console */
+ase_ssize_t awk_extio_console (int cmd, void* arg, ase_char_t* data, ase_size_t size)
+{
+	ase_awk_extio_t* epa = (ase_awk_extio_t*)arg;
+
+	if (cmd == ASE_AWK_IO_OPEN)
+	{
+		if (epa->mode == ASE_AWK_EXTIO_CONSOLE_READ)
+		{
+			FILE* fp = ase_fopen (data_file, ASE_T("r"));
+			if (fp == ASE_NULL) return -1;
+
+			if (ase_awk_setfilename (
+				epa->run, data_file, ase_strlen(data_file)) == -1)
+			{
+				fclose (fp);
+				return -1;
+			}
+
+			epa->handle = fp;
+
+			return 1;
+		}
+		else if (epa->mode == ASE_AWK_EXTIO_CONSOLE_WRITE)
+		{
+			epa->handle = stdout;
+			return 1;
+		}
+
+		return -1;
+	}
+	else if (cmd == ASE_AWK_IO_CLOSE)
+	{
+		fclose ((FILE*)epa->handle);
+		epa->handle = NULL;
+		return 0;
+	}
+	else if (cmd == ASE_AWK_IO_READ)
+	{
+		while (ase_fgets (data, size, (FILE*)epa->handle) == ASE_NULL)
+		{
+			if (ferror((FILE*)epa->handle)) return -1;
+			return 0;
+		}
+
+		return ase_strlen(data);
+	}
+	else if (cmd == ASE_AWK_IO_WRITE)
+	{
+		int n = ase_fprintf ((FILE*)epa->handle, ASE_T("%.*s"), size, data);
+		if (n < 0) return -1;
+
+		return size;
+	}
+	else if (cmd == ASE_AWK_IO_FLUSH)
+	{
+		if (fflush ((FILE*)epa->handle) == EOF) return -1;
+		return 0;
+	}
+	else if (cmd == ASE_AWK_IO_NEXT)
+	{
+		return -1;
+	}
+
+	return -1;
+}
+}}}
+
+External Input-Output Handler.
+
+{{{
+int ase_main (int argc, ase_char_t* argv[])
+{
+	ase_awk_t* awk;
+
+	ase_awk_prmfns_t prmfns;
+	ase_awk_srcios_t srcios;
+	ase_awk_runios_t runios;
+
+	struct awk_src_io src_io = { NULL, NULL };
+
+	if (argc != 3)
+	{
+		ase_printf (ASE_T("Usage: %s source-file data-file\n"), argv[0]);
+		return -1;
+	}
+
+	src_io.file = argv[1];
+	data_file = argv[2];
+
+	ase_memset (&prmfns, 0, ASE_SIZEOF(prmfns));
+
+	prmfns.mmgr.malloc      = awk_malloc;
+	prmfns.mmgr.realloc     = awk_realloc;
+	prmfns.mmgr.free        = awk_free;
+	prmfns.mmgr.custom_data = ASE_NULL;
+
+	prmfns.ccls.is_upper    = awk_isupper;
+	prmfns.ccls.is_lower    = awk_islower;
+	prmfns.ccls.is_alpha    = awk_isalpha;
+	prmfns.ccls.is_digit    = awk_isdigit;
+	prmfns.ccls.is_xdigit   = awk_isxdigit;
+	prmfns.ccls.is_alnum    = awk_isalnum;
+	prmfns.ccls.is_space    = awk_isspace;
+	prmfns.ccls.is_print    = awk_isprint;
+	prmfns.ccls.is_graph    = awk_isgraph;
+	prmfns.ccls.is_cntrl    = awk_iscntrl;
+	prmfns.ccls.is_punct    = awk_ispunct;
+	prmfns.ccls.to_upper    = awk_toupper;
+	prmfns.ccls.to_lower    = awk_tolower;
+	prmfns.ccls.custom_data = ASE_NULL;
+
+	prmfns.misc.pow         = awk_pow;
+	prmfns.misc.sprintf     = awk_sprintf;
+	prmfns.misc.dprintf     = awk_dprintf;
+	prmfns.misc.custom_data = ASE_NULL;
+
+	if ((awk = ase_awk_open(&prmfns, ASE_NULL)) == ASE_NULL) 
+	{
+		ase_printf (ASE_T("ERROR: cannot open awk\n"));
+		return -1;
+	}
+
+	ase_awk_setoption (awk, 
+		ASE_AWK_IMPLICIT | ASE_AWK_EXPLICIT | ASE_AWK_UNIQUEFN | 
+		ASE_AWK_IDIV | ASE_AWK_SHADING | ASE_AWK_SHIFT | 
+		ASE_AWK_EXTIO | ASE_AWK_BLOCKLESS | ASE_AWK_STRBASEONE | 
+		ASE_AWK_STRIPSPACES | ASE_AWK_NEXTOFILE);
+
+	srcios.in = awk_srcio_in;
+	srcios.out = ASE_NULL;
+	srcios.custom_data = &src_io;
+
+	if (ase_awk_parse (awk, &srcios) == -1) 
+	{
+		ase_printf (
+			ASE_T("PARSE ERROR: CODE [%d] LINE [%u] %s\n"), 
+			ase_awk_geterrnum(awk),
+			(unsigned int)ase_awk_geterrlin(awk), 
+			ase_awk_geterrmsg(awk));
+		ase_awk_close (awk);
+		return -1;
+	}
+
+	runios.pipe = awk_extio_pipe;
+	runios.file = awk_extio_file;
+	runios.console = awk_extio_console;
+	runios.custom_data = ASE_NULL;
+
+	if (ase_awk_run (awk, ASE_NULL, &runios, ASE_NULL, ASE_NULL, ASE_NULL) == -1)
+	{
+		ase_printf (
+			ASE_T("RUN ERROR: CODE [%d] LINE [%u] %s\n"), 
+			ase_awk_geterrnum(awk),
+			(unsigned int)ase_awk_geterrlin(awk), 
+			ase_awk_geterrmsg(awk));
+
+		ase_awk_close (awk);
+		return -1;
+	}
+
+	ase_awk_close (awk);
+	return 0;
+}
+}}}
+
+The main function.

ase/doc/awk.man

@@ -0,0 +1,93 @@
+.title Introduction To ASE AWK
+
+== OVERVIEW ==
+
+=== What is it? ===
+'''''ASE AWK''''' is an embeddable implementation of the AWK programming language. It is composed of a set of C functions to help programmers embed the AWK interpreter to their own applications easily. 
+
+=== What does it do? ===
+'''''ASE AWK''''' can do most of the things that other existing AWK interpreters can do. <TODO:>
+
+=== Differences with other implementations ===
+There exist a number of AWK interpreters available. Most of Unix/Linux operating systems come with an AWK interpreter. <TODO:>
+
+== DESCRIPTION ==
+
+=== Interpreter ===
+Multiple instances of interpreters can be created in a single application and each instance of the interpreter created maintains its own state in the data structure pointed at by its handle of the type ''ase_awk_t''.
+
+ * ase_awk_t - an abstract type to an interpreter object.
+ * ase_awk_open - creates an interpreter object.
+ * ase_awk_close - destroys the interprer object created by ase_awk_open.
+
+{{{
+ase_awk_t* ase_awk_open (void);
+void ase_awk_close (ase_awk_t* awk); 
+}}}
+
+The interpreter provides two distinct functionalites in large; the parser and the executor. The parser transforms the source code into the internal parse tree and the executor evaluates the parse tree and runs the code.
+
+{{{
+int ase_awk_parse (ase_awk_t* awk);
+int ase_awk_run (ase_awk_t* awk, ase_awk_io_t txtio, void* txtio_arg); 
+}}}
+
+=== IO Handlers ===
+'''''ASE AWK''''' does not provide any built-in IO handling routines. Instead, it requires users to provide them. 4 different IO streams should be provided to take full advantage of the interpreter.
+
+ * Source code input
+ * Source code output
+ * Data input
+ * Data output
+
+{{{
+enum 
+{
+	XP_AWK_INPUT_OPEN   = 0,
+	XP_AWK_INPUT_CLOSE  = 1,
+	XP_AWK_INPUT_NEXT   = 2,
+	XP_AWK_INPUT_DATA   = 3,
+
+	XP_AWK_OUTPUT_OPEN  = 4,
+	XP_AWK_OUTPUT_CLOSE = 5,
+	XP_AWK_OUTPUT_NEXT  = 6,
+	XP_AWK_OUTPUT_DATA  = 7
+};
+
+typedef ase_ssize_t (*ase_awk_io_t) (int cmd, void* arg, ase_char_t* data, ase_size_t count);
+}}}
+
+=== Miscellaneous Functions ===
+'''''ASE AWK''''' provides extra utility routines as well as the interpreter. These routines used by the interpreter can be accessed from the interested applications directly without regard to the interpreter.
+
+==== String ====
+
+==== Conversion ====
+ * ase_awk_strtolong - convert a numeric string to an integer of the ase_long_t type. 
+ * ase_awk_strtoreal - convert a numeric string to a decimal number of the ase_real_t type.
+
+{{{
+ase_long_t ase_awk_strtolong (const ase_char_t* str, int base, const ase_char_t** endptr); 
+ase_real_t ase_awk_strtoreal (const ase_char_t* str); 
+}}}
+
+==== Regular Expression ====
+The regular expression routines built into the interpreter can replace other regular expression libraries available. By utilizing this, the application can have the identical regular expression functionalities as the embedded AWK interpreter.
+
+{{{
+ase_awk_rex_t* ase_awk_rex_open (ase_awk_rex_t* rex);
+void ase_awk_rex_close (ase_awk_rex_t* rex);
+}}}
+
+=== User-defined Built-in Functions ===
+Custom built-in functions can be added to the interpreter. This requires the deeper look into the internals of the interpreter.
+
+== EXAMPLE ==
+{{{
+#include <xp/awk/awk.h>
+
+int ase_main ()
+{
+	return 0;
+}
+}}}

ase/doc/diff.man

@@ -0,0 +1,11 @@
+== Difference From The Standard AWK ==
+
+== line terminiator ==
+it doesn't accept the new line as a line terminator. 
+
+== print/printf ==
+if the statement succeeds, it sets ERRNO to 0. otherwise, it sets ERRNO to -1.
+
+
+
+

ase/doc/doc.css

@@ -0,0 +1,86 @@
+body 
+{
+	font-family: verdana, "times new roman", tahoma, lucida, sans-serif;
+	background-color: white;
+	color: black;
+	#padding: 10px 10px 10px 10px;
+
+	font-size: 90%; 
+	padding-left: 10px;
+	padding-right: 10px;
+	line-height: 1.3;
+	text-align: justify;
+}
+
+#a:link { color: #F89E59;}
+#a:visited { color: #F89E59;}
+#a:hover { color:#000000;}
+
+h1,h2,h3,h4,h5 
+{
+	font-family: tahoma, "times new roman", verdana;
+	border-bottom: 1px solid #779098;
+}
+h1 { font-size: 120%; }
+h2 { font-size: 115%; padding-left: 5px; }
+h3 { font-size: 110%; padding-left: 10px; }
+h4 { font-size: 105%; padding-left: 15px; }
+h5 { font-size: 100%; padding-left: 20px; }
+
+.header 
+{
+	font-family: verdana, tahoma;
+	font-size: 120%;
+	font-weight: bold;
+	#padding-right: 20px;
+	text-decoration: none;
+	border-bottom: 1px solid black;
+}
+
+.footer 
+{
+	font-family: "times new roman", tahoma;
+	font-size: 14px;
+	#padding-right: 20px;
+	text-decoration: none;
+	text-align: right;
+	border-top: 1px solid black;
+}
+
+.contents
+{
+	font-family: "times new roman", tahoma;
+	font-size: 95%; 
+}
+
+.maintext
+{
+	font-size: 90%; 
+	#color: #555555;
+	color: black;
+	padding-left: 20px;
+	padding-right: 20px;
+	line-height: 1.3;
+	text-align: justify;
+}
+
+pre.code 
+{
+	font-family: "Lucida TypeWriter", monotype, lucida, fixed;
+	font-size: 80%;
+	padding: 6px 6px 6px 6px;
+	xbackground-color: #000000;
+	xcolor: #FFD700; 
+	#border: 1px dashed #779098;
+	#border: 1px solid #779098;
+	border: none;
+	background-color: yellow;
+}
+
+.linenum
+{
+	font-weight: bold;
+}
+
+
+

ase/doc/embed.man

@@ -0,0 +1,51 @@
+.title Embedding AWK
+
+To embed the awk interpreter to an application, the developer should provide the following routines.
+
+ * System functions including memory management
+ * Source code I/O functions
+ * I/O functions to interface with the console, files, and pipes.
+
+ase_awk_open creates an awk object and requires a pointer to a structure holding system functions. The structure is described in ase_awk_prmfns_t.
+
+{{{
+struct ase_awk_prmfns_t
+{
+	/* memory */
+	void* (*malloc) (ase_size_t n, void* custom_data);
+	void* (*realloc) (void* ptr, ase_size_t n, void* custom_data);
+	void  (*free) (void* ptr, void* custom_data);
+
+	/* thread lock */
+	ase_awk_lk_t lock;
+	ase_awk_lk_t unlock;
+
+	/* character class */
+	ase_bool_t (*is_upper)  (ase_cint_t c);
+	ase_bool_t (*is_lower)  (ase_cint_t c);
+	ase_bool_t (*is_alpha)  (ase_cint_t c);
+	ase_bool_t (*is_digit)  (ase_cint_t c);
+	ase_bool_t (*is_xdigit) (ase_cint_t c);
+	ase_bool_t (*is_alnum)  (ase_cint_t c);
+	ase_bool_t (*is_space)  (ase_cint_t c);
+	ase_bool_t (*is_print)  (ase_cint_t c);
+	ase_bool_t (*is_graph)  (ase_cint_t c);
+	ase_bool_t (*is_cntrl)  (ase_cint_t c);
+	ase_bool_t (*is_punct)  (ase_cint_t c);
+	ase_cint_t (*to_upper)  (ase_cint_t c);
+	ase_cint_t (*to_lower)  (ase_cint_t c);
+
+	/* utilities */
+	void* (*memcpy) (void* dst, const void* src, ase_size_t n);
+	void* (*memset) (void* dst, int val, ase_size_t n);
+	ase_real_t (*pow) (ase_real_t x, ase_real_t y);
+
+	int (*sprintf) (ase_char_t* buf, ase_size_t size, const ase_char_t* fmt, ...);
+	void (*aprintf) (const ase_char_t* fmt, ...); /* assertion */
+	void (*dprintf) (const ase_char_t* fmt, ...); /* debug */
+	void (*abort) (void);
+
+	void* custom_data;
+};
+}}}
+

ase/doc/license.man

@@ -0,0 +1,19 @@
+.title ASE License Agreement
+
+Software License Agreement (BSD License)
+
+Copyright (c) 2006-2007, Hyung-Hwan Chung
+All rights reserved.
+
+Redistribution and use of this software in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+[[[
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of the copyright owner nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+]]]
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT OWNER AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

ase/doc/lsp-en.man

@@ -0,0 +1,22 @@
+
+= ASELSP =
+
+ASELSP is an implementation of a lisp-like language for embedding purposes.
+
+== Types ==
+
+[[[
+* ase_lsp_t
+* ase_lsp_io_t
+* ase_lsp_obj_t
+]]]
+
+== Functions ==
+
+[[[
+* ase_lsp_open
+* ase_lsp_close
+* ase_lsp_read
+* ase_lsp_eval
+* ase_lsp_print
+]]]

ase/doc/quickstart-en.man

@@ -0,0 +1,118 @@
+.title ASE Quick Start Guide
+
+= ASE Quick Start Guide =
+
+The first step in using this library is to build it. This document shows how to build the core library on various operating systems.
+
+== Source Code Directories ==
+
+The source code is organized in the following directory structure.
+
+{{{
+ase +- cmn  .................... contains common functions and macros.
+    +- utl  .................... contains more general-purpose utillity 
+    |                            functions and macros.
+    +- awk  .................... implementation of the awk processor.
+    +- lsp  .................... implementation of the lisp processor.
+    +- com  .................... COM wrapper of the processors.
+    +- test +- awk  ............ contains test program for the awk processor.
+            +- lsp  ............ contains test programs for the lisp processor.
+            +- com  ............ contains test programs for the COM module.
+}}}
+
+== Unix/Linux ==
+
+You may run the [[configure]] script on most of the supported operation systems to set up the build environment and then run the [[make]] utility.
+
+{{{
+$ ./configure
+$ make 
+}}}
+
+The [[make]] utility visits each module subdirectory and build binary files. The library files are placed in the [[release/lib]] directory and the executable files in the [[release/bin]] directory.
+
+If you appened the option [[--enable-debug]] to the [[configure]] script, the files would be located in [[debug/lib]] and [[debug/bin]] directory. Besides, it sets up the environment to be more debugging friendly.
+
+{{{
+$ ./configure --enable-debug
+$ make
+}}}
+
+Refer to the following table for the output location of generated files.
+
+{{{
+---------------------------------------------------------------------------
+mode     executable files     library files        include files
+---------------------------------------------------------------------------
+release  ${top}/release/bin   ${top}/release/lib   ${top}/release/inc
+debug    ${top)/debug/bin     $(top)/debug/lib     ${top}/debug/inc
+---------------------------------------------------------------------------
+
+* ${top} - the top level directory
+}}}
+
+If you have preference for a particular compiler and the flags, you may explicitly specify them when you run the [[configure]] script. Here are presented a few such examples.
+
+{{{
+# HP-UX B.11.23 with HP ANSI C 
+CC=cc CFLAGS="-O2 +DD64" LDFLAGS="+DD64" ./configure # 64-bit
+CC=cc CFLAGS="-O2 +DD32" LDFLAGS="+DD32" ./configure # 32-bit
+
+# SCO OpenServer Release 5.0.7 (SCO_SV 3.2 5.0.7) with SCO OpenServer Development System
+CC=cc CFLAGS="-Xc -a ansi -O2" ./configure
+
+# Solaris 10 with GCC
+CC=gcc CFLAGS="-Wall -O2 -m64" LDFLAGS="-m64" ./configure # 64-bit
+CC=gcc CFLAGS="-Wall -O2" ./configure # 32-bit
+}}}
+
+You may specify the C++ compiler with [[CXX]] and its flags in [[CXXFLAGS]].
+
+The JNI library for JAVA is built automatically if required JNI header files are detected by the [[configure]] script. Make sure that the [[javac]] command is included in the [[PATH]] environment variable for this. The JAVA class files are built with the [[javac]] command detected as well. The {ant,http://ant.apache.org} utility from the Apache Software Foundataion can be used to build the java class files. The [[build.xml]] file is provided at the top-level directory for this.
+
+== OpenVMS ==
+
+You may use the [[mms]] command or the [[mmk]] command to build the library. No counterpart for the [[configure]] script is provided. As not top-level build script is provided, you have to run the command in each directory that you want to build the library in.
+
+Let's build the AWK library and its test program, for instance.
+
+{{{
+set default [.ase.cmn]
+mms
+set default [-.awk]
+mms
+set default [-.utl]
+mms
+set default [-.test.awk]
+mms
+}}}
+
+For those who are not familar with OpenVMS, here is one of the ways how to run the test program.
+
+{{{
+; define the foreign command.
+aseawk :== $DISK$GEIN_SYS:[USERS.BACON.ASE.TEST.AWK]aseawk.exe
+; run the command.
+aseawk -f hello.awk
+}}}
+
+== MS-Windows ==
+
+You may use the Visual Studio 6 or later to open the project. But you need Visual Studio 2003 or later to build the .NET related projects. Otherwise, open the command-line build environment and use the [[make]] utility.
+
+A set of make scripts is provided to support the Microsoft build environement and the Borland build environment. The script for the Miscrosoft build environment is named [[makefile.msw.cl]] while it is [[makefile.msw.bcc]] for the Borland counterpart.
+
+If you are building the AWK library and the test program, this is probably what you have to do.
+
+{{{
+cd ase\cmn
+nmake /f makefile.msw.cl
+cd ..\awk
+nmake /f makefile.msw.cl
+cd ..\utl
+nmake /f makefile.msw.cl
+cd ..\test\awk
+nmake /f makefile.msw.cl
+}}}
+
+However, The COM module can only be built within the Visual Studio environment. After having built the COM module, you may open [[ase/test/com/asetestcom.vbp]] for testing.

ase/doc/quickstart-ko.man

@@ -0,0 +1,116 @@
+.title ASE 시작하기
+
+= ASE 시작하기 =
+
+본 문서는 ASE를 사용하기위해서 필요한 정보를 제공한다.
+
+== 소스코드 디렉토리 ==
+
+소스코드는 다음과 같은 디렉토리로 구성된다.
+
+{{{
+ase +- cmn  .................... 공통 함수와 매크로를 포함한다.
+    +- utl  .................... 보다 일반적인 공통 함수와 매크로를 포함한다.
+    +- awk  .................... AWK 처리기
+    +- lsp  .................... LISP 처리기
+    +- com  .................... 각 처리기들의 COM 래퍼모듈
+    +- test +- awk  ............ AWK 처리기 시험 프로그램
+            +- lsp  ............ LISP 처리기 시험 프로그램
+            +- com  ............ COM 래퍼모듈 시험 프로그램
+}}}
+
+== 빌드 ==
+
+각종 운영체제에서 어떻게 ASE를 빌드하는지 보여준다.
+
+=== Unix/Linux ===
+
+[[configure]]스크립트를 실행한후 [[make]]프로그램을 실행한다. 
+
+{{{
+$ ./configure
+$ make 
+}}}
+[[configure]]스크립트는 해당 시스템의 정보를 수집하여 빌드환경을 설정하고 [[make]]는 각각의 서브다이렉트리를 방문해서 바이너리 파일을 만든다. 라이브러리 파일을 [[release/lib]]에, 실행파일들읜 [[release/bin]]에 만들어 진다.
+
+[[--enable-debug]]를 [[configure]]에 사용한 경우에는, 빌드환경이 디버깅에 적합하도록 만들어진다. [[make]]를 실행하면 결과 파일들은 [[debug/lib]]와 [[debug/bin]]에 만들어 진다.
+
+{{{
+$ ./configure --enable-debug
+$ make
+}}}
+
+다음의 표는 빌드환경별로 파일이 만들어지는 위치를 보여준다.
+
+{{{
+---------------------------------------------------------------------------
+모드     실행파일             라이브러리파일       헤더파일
+---------------------------------------------------------------------------
+release  ${top}/release/bin   ${top}/release/lib   ${top}/release/inc
+debug    ${top)/debug/bin     $(top)/debug/lib     ${top}/debug/inc
+---------------------------------------------------------------------------
+
+* ${top} - 최상위 디렉토리
+}}}
+
+특정한 컴파일러와 컴파일러 옵션을 사용하고 싶을때는 [[configure]]를 실행할때 이를 명시해야 한다. 다음의 예들을 보라.
+
+{{{
+# HP-UX B.11.23 with HP ANSI C 
+CC=cc CFLAGS="-O2 +DD64" LDFLAGS="+DD64" ./configure # 64-bit
+CC=cc CFLAGS="-O2 +DD32" LDFLAGS="+DD32" ./configure # 32-bit
+
+# SCO OpenServer Release 5.0.7 (SCO_SV 3.2 5.0.7) with SCO OpenServer Development System
+CC=cc CFLAGS="-Xc -a ansi -O2" ./configure
+
+# Solaris 10 with GCC
+CC=gcc CFLAGS="-Wall -O2 -m64" LDFLAGS="-m64" ./configure # 64-bit
+CC=gcc CFLAGS="-Wall -O2" ./configure # 32-bit
+}}}
+
+C++컴파일러와 옵션은 [[CXX]]와 [[CXXFLAGS]]을 사용해서 명시하면 된다.
+
+JNI헤더파일을 찾을수 있으면 [[configure]]는 JNI라이브러리와 클래스파일들이 만들어 질수 있도록 빌드환경을 설정한다. 이를 위해서 [[javac]]명령어를 [[PATH]]환경변수에 설정된 경로에서 찿고, 이 정보를 이용해서 JNI헤더파일을 찾아낸다. 아파치재단의 {ant,http://ant.apache.org}를 이용하여 자바클래스파일들을 만들수도 있다. 이를 위해서 [[build.xml]]파일이 최상위 디렉토리에 제공된다.
+
+=== OpenVMS ===
+
+OpenVMS에서는 [[mms]]나 [[mmk]]명령어를 사용해야 한다. 다만 [[configure]]같은 환경설정 스크립트가 제공되지 않으므로, 필요한 경우 [[descrip.mms]]파일을 직접 편집해야 한다.
+
+예를 들어, awk라이브러리와 시험프로그램을 만들려면 필요한 서브디렉토리에서 [[mms]]나 [[mmk]]를 실행하면 된다.
+
+{{{
+set default [.ase.cmn]
+mms
+set default [-.awk]
+mms
+set default [-.utl]
+mms
+set default [-.test.awk]
+mms
+}}}
+
+OpenVMS에 익숙하지 않은 사용자라면 다음의 방법으로 만들어진 시험프로그램을 실행해볼수 있다.
+
+{{{
+; define the foreign command.
+aseawk :== $DISK$GEIN_SYS:[USERS.BACON.ASE.TEST.AWK]aseawk.exe
+; run the command.
+aseawk -f hello.awk
+}}}
+
+=== MS-Windows ===
+
+윈도우즈에서는 비쥬얼스튜디오6이나 그 이후 버전이 필요하다. 닷넷관련 프로젝트를 빌드하려면 비쥬얼슈트디오2003이나 그 이후 버전이 필요하다.
+
+== 바이너리파일 ==
+
+빌드에 성공하면 다음과 같은 파일들이 만들어 진다.
+
+{{{
+lib +- libaseawk.a
+    +- libaselsp.a
+    +- libasecmn.a 
+    +- libaseutl.a 
+
+bin
+}}}