ase/doc/en/awk-lang.man

@@ -0,0 +1,198 @@
+.title AWK Language
+.tabstop 6
+
+Most of the AWK language features are supported. This documents shows notable language features that might be different from other implementations.
+
+== Variable ==
+
+A local variable and a global variable are supported if ASE_AWK_EXPLICIT is enabled. ASE_AWK_IMPLICIT is to enable a named variable. You may enable both options to support both types of variables. Either should be enabled for the language to be useful, however. 
+
+A local variable can be declared at the top of each block before any statements are encountered. A global variable can be declared in any places outside a function and a pattern-action block.
+
+{{{
+global a, b;
+global c;
+
+BEGIN {
+	local x, y;
+	a = 30; x = 30; x = a + 40; print x; }
+}
+}}}
+
+{{|
+! Code
+! Description
+|-
+| function a() { }
+  BEGIN { ##-a=20;-## }
+| A function and a named variable cannot have the same name. A named variable requires ASE_AWK_IMPLICIT to be enabled.
+|-
+| function a() { }
+
+  BEGIN { 
+  	local a;
+  	a = 20; 
+  }
+| A local variable can shade the same function name. The deparsed output shows this.
+
+  function a ()
+  {
+  }
+  BEGIN {
+  	local __local0;
+  	__local0 = 20;
+  }
+
+  Local variable declaration requires ASE_AWK_EXPLICIT, though.
+|-
+| global a;
+  function ##-a()-## { }
+  
+  function a() { }
+  global  ##-a-##;
+| A function and a global variable cannot have the same name.
+|-
+| function fn () { 
+  	x = 20;
+  	return x;
+  }
+
+  global x;
+
+  BEGIN { 
+  	x = 30;
+  	print fn ();
+  	print x; 
+  }
+
+| A global variable is visible after it is declared to the remaining part of the program. x inside fn is x named variable while x in BEGIN is a global variable.
+
+  global __global17;
+  function fn ()
+  {
+  	x = 20;
+  	return x;
+  }
+  BEGIN {
+  	__global17 = 30;
+  	print fn ();
+  	print __global17;
+  }
+|-
+| global x;
+  BEGIN {
+  	x = 1;
+  	{
+  		local x;
+  		x = 2;
+  		{
+  			local x;
+  			x = 3;
+  			print x;
+  		}
+  		print x;
+  	}
+  	print x;
+  }
+| A local variable can shade a global variable and a local variable at outer scope. 
+
+  global __global17;
+
+  BEGIN {
+  	local __local0, __local1;
+  	__global17 = 1;
+  	{
+  		__local0 = 2;
+  		{
+  			__local1 = 3;
+  			print __local1;
+  		}
+  		print __local0;
+  	}
+  	print __global17;
+  }
+|}}
+
+
+== Parameter ==
+
+A parameter name can shade a enclosing function name. The following table shows the details.
+
+{{|
+! Code
+! Description
+|-
+| function f(f) { print f; }
+| A parameter name can be the same as the enclosing function name.
+|-
+| function f(f) { ##-f("hello")-##; }
+| A resursive call to the function f is not possible as the third f is the parameter f.
+|-
+| function fn(f) { 
+  	f = 20; 
+  }
+  BEGIN {
+  	f = 50;
+  	fn(100); 
+  	print f; 
+  }
+| 50 is printed. The parameter f in fn doesn't affect the named variable f in BEGIN. The deparsed output shows this clearly.
+
+  function fn (__param0)
+  {
+  	__param0 = 20;
+  }
+  BEGIN {
+  	f = 50;
+  	fn (100);
+  	print f;
+  }
+|}}
+
+== Statement Terminator ==
+A statement must end with a semicolon. A new-line character is treated as whitespace. For this reason, no line continuator, a backslash, is supported. 
+
+{{{
+BEGIN { print "hello, world"; }
+}}}
+
+
+== Function ==
+A blank is allowed between a function name and a left parenthesis. The left bracket for function body doesn't have to be on the same line as the function name and parameters.
+
+{{{
+function fn (x, y)
+{
+	return x + y;
+}
+BEGIN { print fn (10, 20); }
+}}}
+
+== Return ==
+A return statement is allowed in BEGIN and END.
+{{{
+END { return 20; }
+}}}
+
+== Pattern-Action Block ==
+ASE_AWK_BLOCKLESS enables the use of a action-less pattern-action block. Turning it off changes the parser behaviour to treat a block not following any patterns, BEGIN, END. 
+
+{{{
+BEGIN 
+{ print "hello"; }
+{ print "hello2"; }
+}}}
+
+In the code snippet above, the first block is associated with BEGIN while the second block is a patternless pattern-action block that matches any lines of input. It is the same as the following.
+
+{{{
+BEGIN {
+        print "hello";
+}
+
+{
+        print "hello2";
+}
+}}}
+
+