updated README.md

hawk/README.md

@@ -8,19 +8,130 @@
 
 Hawk implements most of the AWK programming language elements with extensions.
 
+### Program Structure
+
+A Hawk program is composed of the following elements at the top level.
+
+ - pattern-action block pair
+   - BEGIN action block pair
+   - END action block pair
+   - action block without a pattern
+   - pattern without an action block
+ - user-defined function
+ - @global variable declaration
+ - @include directive
+ - @pragma directive
+
+However, none of the above is mandatory. Hawk accepts an empty program.
+
+### Pattern-Action Block Pair
+
+A pattern-action pair is composed of a pattern and an action block as shown below:
+
+	pattern {
+		statement
+		statement
+		...
+	}
+
+A pattern can be one of the followings when specified:
+
+ - expression
+ - first-expression, last-expression
+ - *BEGIN*
+ - *END*
+
+An action block is a series of statements enclosed in a curly bracket pair. The *BEGIN* and *END* patterns require an action block while normal patterns don't. When no action block is specified for a normal pattern, it is treated
+as if `{ print $0; }` is specified.
+
+Hawk executes the action block for the *BEGIN* pattern when it starts executing a program; No start-up action is taken if no *BEGIN* pattern-action pair is specified. If a normal pattern-action pair and/or the *END* 
+pattern-action is specified, it reads the standard input stream. For each input line it reads, it checks if a normal pattern expression evaluates to true. For each pattern that evaluates to true, it executes the action block specified for
+the pattern. When it reaches the end of the input stream, it executes the action block for the *END* pattern.
+
+Hawk allows zero or more *BEGIN* patterns. When multiple *BEGIN* patterns are specified, it executes their action blocks in their appearance order in the program. The same applies to the *END* patterns and their action blocks. It 
+doesn't read the standard input stream for programs composed of BEGIN blocks only whereas it reads the stream as long as there is an action block for the END pattern or a normal pattern. It evaluates an empty pattern to true;
+As a result, the action block for an empty pattern is executed for all input lines read.
+
+You can compose a pattern range by putting 2 patterns separated by a comma. The pattern range evaluates to true once the first expression evaluates to true until the last expression evaluates to true.
+
+The following code snippet is a valid Hawk program that prints the string *hello, world* to the console and exits.
+
+
+	BEGIN {
+		print "hello, world";
+	}
+
+This program prints "hello, world" followed by "hello, all" to the console.
+
+	BEGIN {
+		print "hello, world";
+	}
+	BEGIN {
+		print "hello, all";
+	}
+
+For the following text input,
+
+	abcdefgahijklmn
+	1234567890
+	opqrstuvwxyzabc
+	9876543210
+
+this program
+
+	BEGIN { mr=0; my_nr=0; }
+	/abc/ { print "[" $0 "]"; mr++; }
+	{ my_nr++; }
+	END { 
+		print "total records: " NR; 
+		print "total records selfcounted: " my_nr; 
+		print "matching records: " mr; 
+	}
+
+produces the output text like this:
+
+	[abcdefgahijklmn]
+	[opqrstuvwxyzabc]
+	total records: 4
+	total records selfcounted: 4
+	matching records: 2
+
+See the table for the order of execution indicated by the number and the result 
+of pattern evaluation enclosed in parenthesis. The action block is executed if
+the evaluation result is true.
+
+|                                     | START-UP | abcdefgahijklmn | 1234567890 | opqrstuvwxyzabc | 9876543210 | SHUTDOWN |
+|-------------------------------------|----------|-----------------|------------|-----------------|------------|----------|
+| `BEGIN { mr = 0; my_nr=0; }`        | 1(true)  |                 |            |                 |            |          |
+| `/abc/ { print "[" $0 "]"; mr++; }` |          | 2(true)         | 4(false)   | 6(true)         | 8(false)   |          |
+| `{ my_nr++; }`                      |          | 3(true)         | 5(true)    | 7(true)         | 9(true)    |          |
+| `END { print ... }`                 |          |                 |            |                 |            | 10(true) | 
+
+For the same input, this program shows how to use a ranged pattern.
+
+	/abc/,/stu/ { print "[" $0 "]"; }
+
+It produces the output text like this:
+
+	[abcdefgahijklmn]
+	[1234567890]
+	[opqrstuvwxyzabc]
+
+The regular expression `/abc/` matches the first input line and `/stu/` matches the
+third input line. So the range is true between the first input line and the
+third input line inclusive.
 
 ### Entry Point
 
-You may change the entry point of your script by setting a function name with @pragma entry.
+The typical execution begins with the BEGIN block, goes through pattern-action blocks, and eaches the END block. If you like to use a function as an entry point, you may set a function name with @pragma entry.
 
-```
 	@pragma entry main
 
 	function main ()
 	{
 		print "hello, world";
 	}
-```
+
 
 ### Value
 
@@ -41,24 +152,20 @@ function main ()
 
 In AWK, the caller can pass an uninitialized variable as a function parameter and get a changed value if the callled function sets it to an array.
 
-```
+
 	function q(a) {a[1]=20; a[2]=30;}
 	BEGIN { q(x); for (i in x) print i, x[i]; }
-```
 
 In Hawk, you can prefix the pramater name with & to indicate call-by-reference for the same effect.
 
-```
 	function q(&a) {a[1]=20; a[2]=30;}
 	BEGIN { q(x); for (i in x) print i, x[i]; }
-```
+
 
 Alternatively, you may form an array before passing it to a function.
 
-```
 	function q(a) {a[1]=20; a[2]=30;}
 	BEGIN { x[3]=99; q(x); for (i in x) print i, x[i]; }'
-```
 
 
 ## Basic Modules <a name="basic-modules"></a>
@@ -71,8 +178,17 @@ BEGIN { x[3]=99; q(x); for (i in x) print i, x[i]; }'
 
 ## Embedding Guide <a name="embedding-guide"></a>
 
+To use hawk in your program, do the followings:
+
+- create a hawk instance
+- parse a source script
+- create a runtime context
+- trigger execution on the runtime context
+- destroy the runtime context
+- destroy the hawk instance
+
+The following sample illustrates the basic steps hightlighed above.
 
-```
 	#include <hawk-std.h>
 	#include <stdio.h>
 	#include <string.h>
@@ -92,31 +208,31 @@ int main ()
 		hawk_t* hawk = HAWK_NULL;
 		hawk_rtx_t* rtx = HAWK_NULL;
 		hawk_val_t* retv;
-
 		hawk_parsestd_t psin[2];
-
 		int ret;
 
-	hawk = hawk_openstd(0, HAWK_NULL);
+		hawk = hawk_openstd(0, HAWK_NULL); /* create a hawk instance */
 		if (!hawk)  
 		{
 			fprintf (stderr, "ERROR: cannot open hawk\n");
 			ret = -1; goto oops;
 		}
 
+		/* set up source script file to read in */
 		memset (&psin, 0, HAWK_SIZEOF(psin));
-	psin[0].type = HAWK_PARSESTD_BCS;
+		psin[0].type = HAWK_PARSESTD_BCS;  /* specify the first script path */
 		psin[0].u.bcs.ptr = (hawk_bch_t*)src;
 		psin[0].u.bcs.len = hawk_count_bcstr(src);
-	psin[1].type = HAWK_PARSESTD_NULL;
+		psin[1].type = HAWK_PARSESTD_NULL; /* indicate the no more script to read */
 
-	ret = hawk_parsestd(hawk, psin, HAWK_NULL);
+		ret = hawk_parsestd(hawk, psin, HAWK_NULL); /* parse the script */
 		if (ret <= -1)
 		{
 			hawk_logbfmt (hawk, HAWK_LOG_STDERR, "ERROR(parse): %js\n", hawk_geterrmsg(hawk));
 			ret = -1; goto oops;
 		}
 
+		/* create a runtime context needed for execution */
 		rtx = hawk_rtx_openstd (
 			hawk, 
 			0,
@@ -131,6 +247,7 @@ int main ()
 			ret = -1; goto oops;
 		}
 
+		/* execute the BEGIN/pattern-action/END blocks */
 		retv = hawk_rtx_loop(rtx);
 		if (!retv)
 		{
@@ -138,12 +255,15 @@ int main ()
 			ret = -1; goto oops;
 		}
 
+		/* lowered the reference count of the returned value */
 		hawk_rtx_refdownval (rtx, retv);
 		ret = 0;
 
 	oops:
-	if (rtx) hawk_rtx_close (rtx);
+		if (rtx) hawk_rtx_close (rtx); /* destroy the runtime context */
-	if (hawk) hawk_close (hawk);
+		if (hawk) hawk_close (hawk); /* destroy the hawk instance */
 		return -1;
 	}
-```
+
+
+If you prefer C++, you may use the Hawk/HawkStd wrapper classes to simplify the task. The C++ classes are inferior to the C equivalents in that they don't allow creation of multiple runtime contexts over a single hawk instance.

hawk/samples/hawk02.c

@@ -17,31 +17,31 @@ int main ()
 	hawk_t* hawk = HAWK_NULL;
 	hawk_rtx_t* rtx = HAWK_NULL;
 	hawk_val_t* retv;
-
 	hawk_parsestd_t psin[2];
-
 	int ret;
 
-	hawk = hawk_openstd(0, HAWK_NULL);
+	hawk = hawk_openstd(0, HAWK_NULL); /* create a hawk instance */
 	if (!hawk)  
 	{
 		fprintf (stderr, "ERROR: cannot open hawk\n");
 		ret = -1; goto oops;
 	}
 
+	/* set up source script file to read in */
 	memset (&psin, 0, HAWK_SIZEOF(psin));
-	psin[0].type = HAWK_PARSESTD_BCS;
+	psin[0].type = HAWK_PARSESTD_BCS;  /* specify the first script path */
 	psin[0].u.bcs.ptr = (hawk_bch_t*)src;
 	psin[0].u.bcs.len = hawk_count_bcstr(src);
-	psin[1].type = HAWK_PARSESTD_NULL;
+	psin[1].type = HAWK_PARSESTD_NULL; /* indicate the no more script to read */
 
-	ret = hawk_parsestd(hawk, psin, HAWK_NULL);
+	ret = hawk_parsestd(hawk, psin, HAWK_NULL); /* parse the script */
 	if (ret <= -1)
 	{
 		hawk_logbfmt (hawk, HAWK_LOG_STDERR, "ERROR(parse): %js\n", hawk_geterrmsg(hawk));
 		ret = -1; goto oops;
 	}
 
+	/* create a runtime context needed for execution */
 	rtx = hawk_rtx_openstd (
 		hawk, 
 		0,
@@ -56,6 +56,7 @@ int main ()
 		ret = -1; goto oops;
 	}
 
+	/* execute the BEGIN/pattern-action/END blocks */
 	retv = hawk_rtx_loop(rtx);
 	if (!retv)
 	{
@@ -63,12 +64,12 @@ int main ()
 		ret = -1; goto oops;
 	}
 
+	/* lowered the reference count of the returned value */
 	hawk_rtx_refdownval (rtx, retv);
 	ret = 0;
 
 oops:
-	if (rtx) hawk_rtx_close (rtx);
+	if (rtx) hawk_rtx_close (rtx); /* destroy the runtime context */
-	if (hawk) hawk_close (hawk);
+	if (hawk) hawk_close (hawk); /* destroy the hawk instance */
 	return -1;
 }
-