ase/doc/en/ase.man

@@ -0,0 +1,28 @@
+.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, the COM and .NET 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.
+
+[[[
+* {Google Code,http://abiyo.googlecode.com/}
+]]]
+
+== Documentation ==
+
+[[[
+* {Quickstart,quickstart.html}
+* {AWK Embedder's guide,awk-embed.html}
+* {LISP Embedder's guide,lsp-embed.html}
+* {Frequently Asked Questions,faq.html}
+]]]
+
+== Licensing ==
+
+ASE is distributed under a {BSD license,license.html} and is free for all uses.

ase/doc/en/awk-ref.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/en/lsp-embed.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/en/quickstart.man

@@ -0,0 +1,156 @@
+.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
+}}}
+
+The following table shows the output locations of generated files.
+
+{{|
+! Mode
+! Executable Files
+! Library Files
+! Include Files
+|-
+| release  
+| ${ase}/release/bin
+| ${ase}/release/lib
+| ${ase}/release/inc
+|-
+| debug
+| ${ase)/debug/bin
+| $(ase)/debug/lib
+| ${ase}/debug/inc
+|}}
+
+* ${ase} - 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.
+
+{{|
+!
+! 32 Bits
+! 64 Bits
+|-
+| HP-UX B.11.23
+| CC=cc CFLAGS="-O2 +DD32 -D_INCLUDE__STDC_A1_SOURCE" LDFLAGS="+DD32" CXX=aCC CXXFLAGS="-O2 +DD32 -D_INCLUDE__STDC_A1_SOURCE" ./configure
+| CC=cc CFLAGS="-O2 +DD64 -D_INCLUDE__STDC_A1_SOURCE" LDFLAGS="+DD64" CXX=aCC CXXFLAGS="-O2 +DD64 -D_INCLUDE__STDC_A1_SOURCE" ./configure
+|-
+| SCO OpenServer 5.0.7 
+| CC=cc CFLAGS="-Xc -a ansi -O2" ./configure
+|
+|-
+| Solaris 10
+| CC=gcc CFLAGS="-Wall -O2" CXX=g++ CXXFLAGS="-Wall -O2" ./configure
+| CC=gcc CFLAGS="-Wall -O2 -m64" CXX=g++ CXXFLAGS="-Wall -O2 -m64" LDFLAGS="-m64" ./configure 
+|}}
+
+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. 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.
+
+== OpenVMS ==
+
+You may use the [[mms]] command or the [[mmk]] command to build the library. No counterpart for the [[configure]] script is provided. As no 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 [[msw-cl.mak]] while it is [[msw-bcc.mak]] 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 msw-cl.mak
+cd ..\awk
+nmake /f msw-cl.mak
+cd ..\utl
+nmake /f msw-cl.mak
+cd ..\test\awk
+nmake /f msw-cl.mak
+}}}
+
+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/asecom.vbp]] for testing.
+
+
+== Extra Features ==
+
+unicode
+keyword replacement
+error string customization
+
+== Languages ==
+
+{{|
+! Language
+! Status
+! Bindings
+|-
+| AWK
+| Beta-1
+| C,C++,Java,.Net
+|-
+| LISP
+| Experimental
+| C
+|-
+| Javascript
+| Planned
+| C
+|}}