155 lines
4.0 KiB
Plaintext
155 lines
4.0 KiB
Plaintext
/** @page awk AWK
|
|
|
|
@section awk_intro INTRODUCTION
|
|
|
|
QSEAWK is an embeddable AWK interpreter that is a part of the QSE library.
|
|
The design focuses on easy to use APIs
|
|
|
|
A embedding application can
|
|
- add new awk global variables and functions.
|
|
- get and set the value of a global variable.
|
|
- call an awk function.
|
|
- customize I/O handlers for file, pipe, console I/O.
|
|
- embed multiple interpreters independent of each other.
|
|
- run a single script with different I/O streams independently.
|
|
- change language features by setting options.
|
|
|
|
The interpreter implements the language described in the book
|
|
The AWK Programming Language(http://cm.bell-labs.com/cm/cs/awkbook/) with
|
|
some extensions.
|
|
|
|
@section awk_ext EXTENSIONS
|
|
Some language extensions are implemented and they can be enabled by setting the
|
|
corresponding options.
|
|
|
|
@subsection awk_ext_vardecl VARIABLE DECLARATION
|
|
|
|
#QSE_AWK_EXPLICIT enables variable declaration. Variables declared are accessed
|
|
directly bypassing the global named map that stores undeclared variables.
|
|
The keyword @b global introduces a global variable and the keyword @b local
|
|
introduces local variable. Local variable declaraion in a block must be
|
|
located before an expression or a statement appears.
|
|
|
|
@code
|
|
global g1, g2; #declares two global variables g1 and g2
|
|
|
|
BEGIN {
|
|
local a1, a2, a3; # declares three local variables
|
|
|
|
g1 = 300; a1 = 200;
|
|
|
|
{
|
|
local a1; # a1 here hides the a1 at the outer scope
|
|
local g1; # g1 here hides the global g1
|
|
a1 = 10; g1 = 5;
|
|
print a1, g1; # it prints 10 and 5
|
|
}
|
|
|
|
print a1, g1; # it prints 200 and 300
|
|
}
|
|
|
|
@endcode
|
|
|
|
However, turning on #QSE_AWK_EXPLICIT does not disable named variables.
|
|
To disable named variables, you must turn off #QSE_AWK_IMPLICIT.
|
|
|
|
@subsection awk_ext_include INCLUDE
|
|
|
|
The \@include directive inserts the contents of the object specified in the
|
|
following string, typically a file name, as if they appeared in the source
|
|
stream being processed. The directive can only be used at the outmost scope
|
|
where global variable declarations, @b BEGIN, @b END, and/or pattern-action
|
|
blocks appear. To use \@include, you must turn on #QSE_AWK_INCLUDE.
|
|
|
|
@code
|
|
@include "abc.awk"
|
|
BEGIN { func_in_abc (); }
|
|
@endcode
|
|
|
|
@subsection awk_ext_rwpipe TWO-WAY PIPE
|
|
|
|
The two-way pipe indicated by @b || is supproted, in addition to the one-way
|
|
pipe indicated by @b |. Turn on #QSE_AWK_RWPIPE to enable the two-way pipe.
|
|
|
|
@code
|
|
BEGIN {
|
|
print "15" || "sort";
|
|
print "14" || "sort";
|
|
print "13" || "sort";
|
|
print "12" || "sort";
|
|
print "11" || "sort";
|
|
# close the input side of the pipe as 'sort' starts emitting result
|
|
# once the input is closed.
|
|
close ("sort", "r");
|
|
while (("sort" || getline x) > 0) print "xx:", x;
|
|
}
|
|
@endcode
|
|
|
|
@subsection awk_ext_return RETURN
|
|
The return statement is valid in BEGIN blocks, END blocks, and pattern-action
|
|
blocks as well as in functions. The execution of a calling block is aborted
|
|
once the return statement is executed.
|
|
|
|
If #QSE_AWK_MAPTOVAR is on, you can return an arrayed value from a function.
|
|
@code
|
|
function getarray() {
|
|
local a;
|
|
a["one"] = 1;
|
|
a["two"] = 2;
|
|
a["three"] = 3;
|
|
return a;
|
|
}
|
|
|
|
BEGIN {
|
|
local x;
|
|
|
|
x = getarray();
|
|
for (i in x) print i, x[i];
|
|
}
|
|
@endcode
|
|
|
|
@subsection awk_ext_comment COMMENT
|
|
You can use the C-style comment as well as the pound comment.
|
|
|
|
@subsection awk_ext_fnc EXTENDED FUNCTIONS
|
|
index() and match() can accept the third parameter indicating the position
|
|
where the search begins. A negative value indicates a position from the back.
|
|
|
|
@code
|
|
BEGIN {
|
|
xstr = "abcdefabcdefabcdef";
|
|
xsub = "abc";
|
|
xlen = length(xsub);
|
|
|
|
i = 1;
|
|
while ((i = index(xstr, xsub, i)) > 0)
|
|
{
|
|
print i, substr(xstr, i, xlen);
|
|
i += xlen;
|
|
}
|
|
}
|
|
@endcode
|
|
|
|
@subsection awk_ext_fs EXTENDED FS
|
|
@code
|
|
BEGIN { FS="?:\\\"\""; }
|
|
@endcode
|
|
|
|
|
|
@subsection awk_ext_binnum BINARY NUMBER
|
|
Use 0b to begin a binary number sequence.
|
|
|
|
@code
|
|
BEGIN { print 0b1101; }
|
|
@endcode
|
|
|
|
@subsection awk_ext_unicode UNICODE ESCAPE SEQUENCE
|
|
|
|
If QSE is compiled for #QSE_CHAR_IS_WCHAR, you can use \\u and \\U in a
|
|
string to specify a character by unicode.
|
|
|
|
@code
|
|
BEGIN { print "string=>[\uB313\U0000B313]"; }
|
|
@endcode
|
|
*/
|