.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "runawk_modules 3"
.TH runawk_modules 3 "2014-12-26" "" ""
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
runawk \- wrapper for AWK interpreter
.SH "MODULES"
.IX Header "MODULES"
\&\fBrunawk\fR provides dozens of modules.
Below is the documentation for them.
.SS "CR_in.awk"
.IX Subsection "CR_in.awk"
As the name of this module says (_in suffix) this module reads and
optionally changes input lines.
.PP
Carriage-Return symbol at the end of input lines is removed.
This symbol usually appears in Windows text files.
If you want to adapt your script to accept windows files on input,
just put
.PP
.Vb 1
\&    #use "CR_in.awk"
.Ve
.PP
in the very beginning of your script.
.SS "abort.awk"
.IX Subsection "abort.awk"
.IP "\fIabort (\s-1MSG,\s0 [\s-1EXIT_STATUS\s0])\fR" 2
.IX Item "abort (MSG, [EXIT_STATUS])"
print \s-1MSG\s0 to stderr and exits program with
\&\s-1EXIT_STATUS.  EXIT_STATUS\s0 defaults to 1.
.SS "abs.awk"
.IX Subsection "abs.awk"
.IP "\fIabs (V)\fR" 2
.IX Item "abs (V)"
return absolute value of V.
.SS "alt_assert.awk"
.IX Subsection "alt_assert.awk"
.IP "\fIassert (\s-1CONDITION, MSG, STATUS\s0)\fR" 2
.IX Item "assert (CONDITION, MSG, STATUS)"
print an
error message \s-1MSG\s0 to standard error and terminates
the program with \s-1STATUS\s0 exit code if \s-1CONDITION\s0 is false.
.SS "alt_getopt.awk"
.IX Subsection "alt_getopt.awk"
.IP "\fIgetopt(\s-1SHORT_OPTS\s0)\fR" 2
.IX Item "getopt(SHORT_OPTS)"
This function processes \s-1ARGV\s0 array and
returns \s-1TRUE\s0 if option is received, 
received option is saved in 'optopt' variable, option argument (if any)
is saved in 'optarg' variable. Long options (like \-\-help or
\&\-\-long\-option) present in \s-1GNU\s0 libc and \s-1BSD\s0 systems are also supported.
.Sp
\&\s-1NOTE:\s0 alt_getopt.awk module follows rules
from \s-1SUS/POSIX \s0\*(L"Utility Syntax Guidelines\*(R"
.SS "alt_join.awk"
.IX Subsection "alt_join.awk"
.IP "\fIjoin_keys (\s-1HASH, SEP\s0)\fR" 2
.IX Item "join_keys (HASH, SEP)"
return string consisting of all keys from \s-1HASH\s0 separated by \s-1SEP.\s0
.IP "\fIjoin_values (\s-1HASH, SEP\s0)\fR" 2
.IX Item "join_values (HASH, SEP)"
return string consisting of all values from \s-1HASH\s0 separated by \s-1SEP.\s0
.IP "\fIjoin_by_numkeys (\s-1ARRAY, SEP\s0 [, \s-1START\s0 [, \s-1END\s0]])\fR" 2
.IX Item "join_by_numkeys (ARRAY, SEP [, START [, END]])"
return string consisting of all values from \s-1ARRAY\s0
separated by \s-1SEP.\s0 Indices from \s-1START \s0(default: 1) to \s-1END
\&\s0(default: +inf) are analysed. Collecting values is stopped
on index absent in \s-1ARRAY.\s0
.SS "backslash_in.awk"
.IX Subsection "backslash_in.awk"
As the name of this module (_in suffix) says this module
reads and optionally changes input lines.
.PP
Backslash character at the end of line is treated as a sign
that current line is continued on the next one.
Example is below.
.PP
Input:
    a b c\e
    d e f g
    a
    b
    e\e
      f
.PP
What your program using backslash_in.awk will obtain:
    a b cd e f g
    a
    b
    e  f
.SS "basename.awk"
.IX Subsection "basename.awk"
.IP "\fIbasename (\s-1PATH\s0)\fR" 2
.IX Item "basename (PATH)"
return filename portion of the \s-1PATH
\&\s0(the same as \fI\fIdirname\fI\|(3)\fR)
.PP
See example/demo_basename for the sample of usage
.SS "braceexpand.awk"
.IX Subsection "braceexpand.awk"
.IP "\fIbraceexp(\s-1STRING\s0)\fR" 2
.IX Item "braceexp(STRING)"
shell-like brace expansion.
.Sp
For example:
print braceexpand(\*(L"ab{,22{,7,8}}z{8,9}\*(R")
  \-| abz8 abz9 ab22z8 ab22z9 ab227z8 ab227z9 ab228z8 ab228z9
.SS "dirname.awk"
.IX Subsection "dirname.awk"
.IP "\fIdirname (\s-1PATH\s0)\fR" 2
.IX Item "dirname (PATH)"
return dirname portion of the \s-1PATH
\&\s0(the same as \fI\fIdirname\fI\|(3)\fR)
.PP
See example/demo_dirname for the sample of usage
.SS "embed_str.awk"
.IX Subsection "embed_str.awk"
This module reads a program's file, find .begin\-str/.end\-str pairs
and reads lines between them.
.PP
\&\fI\s-1EMBED_STR\s0\fR \- Associative array with string index
.PP
Example:
 Input:
  .begin\-str mymsg
   Line1
   Line2
  .end\-str
 Output (result)
  \s-1EMBED_STR\s0 [\*(L"mymsg\*(R"]=\*(L"Line1\enLine2\*(R"
.PP
See example/demo_embed_str for the sample of usage
.SS "exitnow.awk"
.IX Subsection "exitnow.awk"
.IP "\fIexitnow (\s-1STATUS\s0)\fR" 2
.IX Item "exitnow (STATUS)"
similar to the statement 'exit' but do not run
\&\s-1END\s0 sections.
.SS "fieldwidth.awk"
.IX Subsection "fieldwidth.awk"
By default \s-1AWK\s0 interpreter splits input lines into tokens according
to regular expression that defines \*(L"spaces\*(R" between them using
special variable \s-1FS.\s0 Sometimes it is useful to define a fixed-size
fields for tokens. This is what this module is for. The
functionality of fieldwidths.awk is very close to \s-1GNU\s0 awk's
\&\s-1FIELDWIDTHS\s0 variable.
.IP "\fIfieldwidths(\s-1STRING, FW\s0)\fR" 2
.IX Item "fieldwidths(STRING, FW)"
extracts substrings from \s-1STRING\s0 according to \s-1FW\s0
from the left to the right and assigns \f(CW$1\fR, \f(CW$2\fR etc. and \s-1NF\s0
variable. \s-1FW\s0 is a space separated list of numbers that specify
fields widths.
.IP "\fIfieldwidths0(\s-1FW\s0)\fR" 2
.IX Item "fieldwidths0(FW)"
Does the the same as `fieldwidths' function but splits \f(CW$0\fR instead.
.IP "\fI\s-1FW\s0\fR" 2
.IX Item "FW"
global variable. If it is set to non-empty string, all input
lines are split automatically and the value of variable \s-1FS\s0 is
ignored in this case.
.PP
See example/demo_fieldwidths for the sample of usage
.SS "ftrans_in.awk"
.IX Subsection "ftrans_in.awk"
\&\fIbeginfile()\fR function provided by user is called before file reading
.PP
\&\fIendfile()\fR   function provided by user is called after file reading
.SS "glob.awk"
.IX Subsection "glob.awk"
.IP "\fIglob2ere (\s-1PATTERN\s0)\fR" 2
.IX Item "glob2ere (PATTERN)"
convert glob \s-1PATTERN
\&\s0(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13)
to equivalent extended regular expression
(http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04)
.SS "has_prefix.awk"
.IX Subsection "has_prefix.awk"
.IP "\fIhas_prefix (\s-1STRING, PREFIX\s0)\fR" 2
.IX Item "has_prefix (STRING, PREFIX)"
return \s-1TRUE\s0 if \s-1STRING\s0 begins with \s-1PREFIX\s0
.PP
See example/demo_has_prefix for the sample of usage
.SS "has_suffix.awk"
.IX Subsection "has_suffix.awk"
.IP "\fIhas_suffix(\s-1STRING, SUFFIX\s0)\fR" 2
.IX Item "has_suffix(STRING, SUFFIX)"
return \s-1TRUE\s0 if \s-1STRING\s0 ends with \s-1SUFFIX\s0
.PP
See example/demo_has_suffix for the sample of usage
.SS "heapsort.awk"
.IX Subsection "heapsort.awk"
.IP "\fIheapsort (src_array, dest_remap, start, end)\fR" 2
.IX Item "heapsort (src_array, dest_remap, start, end)"
The content of `src_array' is sorted using awk's rules for
comparing values. Values with indices in range [start, end] are
sorted.  `src_array' array is not changed.
Instead dest_remap array is generated such that
.Sp
.Vb 5
\&  Result:
\&    src_array [dest_remap [start]] <=
\&       <= src_array [dest_remap [start+1]] <=
\&       <= src_array [dest_remap [start+2]] <= ... <=
\&       <= src_array [dest_remap [end]]
\&
\&  \`heapsort\*(Aq algorithm is used.
\&Examples: see demo_heapsort and demo_heapsort2 executables.
.Ve
.IP "\fIheapsort_values (src_hash, dest_remap)\fR" 2
.IX Item "heapsort_values (src_hash, dest_remap)"
The same as `heapsort' described above, but hash values are sorted.
.Sp
.Vb 5
\&  Result: 
\&    src_array [dest_remap [1]] <=
\&       <= src_array [dest_remap [2]] <=
\&       <= src_array [dest_remap [3]] <= ... <=
\&       <= src_array [dest_remap [count]]
\&
\&  \`count\*(Aq, a number of elements in \`src_hash\*(Aq, is a return value.
.Ve
.Sp
Examples: see demo_heapsort3 executable.
.IP "\fIheapsort_indices (src_hash, dest_remap)\fR" 2
.IX Item "heapsort_indices (src_hash, dest_remap)"
The same as `heapsort' described above, but hash indices are sorted.
.Sp
.Vb 5
\&  Result: 
\&    dest_remap [1] <=
\&       <= dest_remap [2] <=
\&       <= dest_remap [3] <= ... <=
\&       <= dest_remap [count]
\&
\&  \`count\*(Aq, a number of elements in \`src_hash\*(Aq, is a return value.
.Ve
.Sp
Examples: demo_ini
.IP "\fIheapsort_fields (dest_remap, [start [, end [, strnum]]])\fR" 2
.IX Item "heapsort_fields (dest_remap, [start [, end [, strnum]]])"
The same as function \*(L"heapsort0\*(R" but \f(CW$1\fR, \f(CW$2\fR... array is sorted.
Note that \f(CW$1\fR, \f(CW$2\fR... are not changed, but dest_remap array is filled in!
The variable \*(L"start\*(R" default to 1, \*(L"end\*(R" \*(-- to \s-1NF.\s0
If \*(L"strnum\*(R" is set to 1, values are forcibly compared as strings.
If \*(L"strnum\*(R" is set to 2, values are forcibly compared as numbers.
.IP "\fIheapsort0 ([start [, end [, strnum]]])\fR" 2
.IX Item "heapsort0 ([start [, end [, strnum]]])"
The same as \*(L"heapsort_fields\*(R" but \f(CW$1\fR, \f(CW$2\fR... are changed.
.SS "ini.awk"
.IX Subsection "ini.awk"
This module provides functions for manipulating .ini files.
See example/demo_ini  for the sample of use.
.IP "\fIread_inifile(\s-1FILENAME, RESULT\s0 [, \s-1SEPARATOR\s0])\fR" 2
.IX Item "read_inifile(FILENAME, RESULT [, SEPARATOR])"
Reads .ini file \s-1FILENAME\s0 and fills array \s-1RESULT,\s0 e.g.
\&\s-1RESULT\s0 [<section5><\s-1SEPARATOR\s0><name6>] = <value5.6> etc.
If \s-1SEPARATOR\s0 is not specified, `.' symbols is used by default.
.PP
Features:
.PP
.Vb 8
\&  \- spaces are allowed everywhere, i.e. at the beginning and end of
\&    line, around \`=\*(Aq separator. THEY ARE STRIPPED!
\&  \- comment lines start with \`;\*(Aq or \`#\*(Aq sign. Comment lines are ignored.
\&  \- values can be surrounded by signle or double quote. In this case
\&    spaces are presenrved, otherwise they are removed from
\&    beginning and at the end of line and replaced with single space
\&    in the middle of the line.
\&  \- Escape character are not supported (yet?).
.Ve
.SS "init_getopt.awk"
.IX Subsection "init_getopt.awk"
Initialization step for power_getopt.awk module.  In some cases it
makes sense to process options in a \fIwhile()\fR loop.  This module
allows doing this.  See the documentation about how options are
initialized in power_getopt.awk module.
.IP "\fIprint_help ()\fR" 2
.IX Item "print_help ()"
display help message.
.SS "io.awk"
.IX Subsection "io.awk"
This module provides a number of \s-1IO\s0 functions.
.IP "\fIis_file(\s-1FILENAME\s0)\fR" 2
.IX Item "is_file(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is a regular file or 0 otherwise.
.IP "\fIis_socket(\s-1FILENAME\s0)\fR" 2
.IX Item "is_socket(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is a socket or 0 otherwise.
.IP "\fIis_dir(\s-1FILENAME\s0)\fR" 2
.IX Item "is_dir(FILENAME)"
returns 1 if the specified \s-1FILENAME
\&\s0 is a dir or 0 otherwise.
.IP "\fIis_exec(\s-1FILENAME\s0)\fR" 2
.IX Item "is_exec(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is executable or 0 otherwise.
.IP "\fIis_fifo(\s-1FILENAME\s0)\fR" 2
.IX Item "is_fifo(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is a \s-1FIFO\s0 or 0 otherwise.
.IP "\fIis_blockdev(\s-1FILENAME\s0)\fR" 2
.IX Item "is_blockdev(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is a block special file or 0 otherwise.
.IP "\fIis_chardev(\s-1FILENAME\s0)\fR" 2
.IX Item "is_chardev(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is a character special file or 0 otherwise.
.IP "\fIis_symlink(\s-1FILENAME\s0)\fR" 2
.IX Item "is_symlink(FILENAME)"
returns 1 if the specified \s-1FILENAME\s0
is a symlink or 0 otherwise.
.IP "\fIfile_size(\s-1FILENAME, USE_STAT_NOT_LSTAT\s0)\fR" 2
.IX Item "file_size(FILENAME, USE_STAT_NOT_LSTAT)"
returns the size of the specified \s-1FILENAME.\s0
If \s-1USE_STAT_NOT_LSTAT\s0 is True, \fIstat\fR\|(2) is used instead of \fIlstat\fR\|(2).
.Sp
.Vb 4
\&  Return value:
\&    \-2 if file doesn\*(Aqt exist
\&    \-1 if file is not a regular file
\&    filesize otherwise
.Ve
.IP "\fIfile_type(\s-1FILENAME, USE_STAT_NOT_LSTAT\s0)\fR" 2
.IX Item "file_type(FILENAME, USE_STAT_NOT_LSTAT)"
returns a single letter that corrspond to the file
type. If \s-1USE_STAT_NOT_LSTAT\s0 is True, \fIstat\fR\|(2) is used instead of \fIlstat\fR\|(2).
.Sp
.Vb 8
\&  Return value:
\&    \-  \-\-  regular file
\&    d  \-\- directory
\&    c  \-\- character device
\&    b  \-\- block device
\&    p  \-\- FIFO
\&    l  \-\- symlink
\&    s  \-\- socket
.Ve
.PP
See example/demo_io for the sample of usage
.SS "isnum.awk"
.IX Subsection "isnum.awk"
.IP "\fIisnum (\s-1NUM\s0)\fR" 2
.IX Item "isnum (NUM)"
returns 1 if an argument is a number
.SS "match_br.awk"
.IX Subsection "match_br.awk"
.IP "\fImatch_br(\s-1STRING, BR_OPEN, BR_CLOSE\s0)\fR" 2
.IX Item "match_br(STRING, BR_OPEN, BR_CLOSE)"
return start position (or zero if failure) of the substring
surrounded by balanced (), [], {} or similar characters
Also sets \s-1RSTART\s0 and \s-1RLENGTH\s0 variables just like
the standard 'match' function does
.Sp
For example:
  print match_br(\*(L"A (B (), C(D,C,F (), 123))\*(R", \*(L"(\*(R", \*(L")\*(R")
  print \s-1RSTART, RLENGTH
 \s0 \-| 3
  \-| 3
  \-| 24
.SS "max.awk"
.IX Subsection "max.awk"
.IP "\fImax, max3, max4, max5\fR" 2
.IX Item "max, max3, max4, max5"
maximum functions
.IP "\fImax_key(\s-1HASH, DFLT\s0)\fR" 2
.IX Item "max_key(HASH, DFLT)"
returns a maximum key in \s-1HASH\s0 or \s-1DFLT\s0 if it is empty
.IP "\fImax_value(\s-1HASH, DFLT\s0)\fR" 2
.IX Item "max_value(HASH, DFLT)"
returns a maximum value in \s-1HASH\s0 or \s-1DFLT\s0 if it is empty
.IP "\fIkey_of_max_value(\s-1HASH, DFLT\s0)\fR" 2
.IX Item "key_of_max_value(HASH, DFLT)"
returns A \s-1KEY OF\s0 maximum value in \s-1HASH\s0 or \s-1DFLT\s0 if it is empty
.SS "min.awk"
.IX Subsection "min.awk"
.IP "\fImin, min3, min4, min5\fR" 2
.IX Item "min, min3, min4, min5"
minimum functions
.IP "\fImin_key(\s-1HASH, DFLT\s0)\fR" 2
.IX Item "min_key(HASH, DFLT)"
returns a minimum key in \s-1HASH\s0 or \s-1DFLT\s0 if it is empty
.IP "\fImin_value(\s-1HASH, DFLT\s0)\fR" 2
.IX Item "min_value(HASH, DFLT)"
returns a minimum value in \s-1HASH\s0 or \s-1DFLT\s0 if it is empty
.IP "\fIkey_of_min_value(\s-1HASH, DFLT\s0)\fR" 2
.IX Item "key_of_min_value(HASH, DFLT)"
returns A \s-1KEY OF\s0 minimum value in \s-1HASH\s0 or \s-1DFLT\s0 if it is empty
.SS "modinfo.awk"
.IX Subsection "modinfo.awk"
This module provides the following variables
.IP "\fI\s-1MODC\s0\fR" 2
.IX Item "MODC"
A number of modules (\-f <filename>) passed to an awk interpreter
.IP "\fI\s-1MODV\s0\fR" 2
.IX Item "MODV"
Array with [0..MODC) indexes of those modules
.IP "\fI\s-1MODMAIN\s0\fR" 2
.IX Item "MODMAIN"
Path to the main module, i.e. program filename
.PP
See example/demo_modinfo for the sample of usage
.SS "multisub.awk"
.IX Subsection "multisub.awk"
.IP "\fImultisub(\s-1STRING,\s0 SUBST_REPLS[, \s-1KEEP\s0])\fR" 2
.IX Item "multisub(STRING, SUBST_REPLS[, KEEP])"
is a substitution function. It searches for
a list of substrings, specified in \s-1SUBST_REPL\s0
in a left-most longest order and (if found) replaces
found fragments with appropriate replacement.
\&\s-1SUBST_REPL\s0 format: \*(L"\s-1SUBSTRING1:REPLACEMENT1   SUBSTRING2:REPLACEMENT2...\*(R".\s0
Three spaces separate substring:replacement pairs from each other.
If \s-1KEEP\s0 is specified and some \s-1REPLACEMENT\s0(N) is equal to it, then
appropriate \s-1SUBSTRING\s0(N) is treated as a regular expression
and matched text is kept as is, i.e. not changed.
.Sp
For example:
     print multisub(\*(L"\s-1ABBABBBBBBAAB\*(R", \s0\*(L"ABB:c   BBA:d   AB:e\*(R")
     |\- ccBBde
.SS "pow.awk"
.IX Subsection "pow.awk"
.IP "\fIpow (X, Y)\fR" 2
.IX Item "pow (X, Y)"
returns the value of X to the exponent Y
.SS "power_getopt.awk"
.IX Subsection "power_getopt.awk"
power_getopt.awk module provides a very easy way to add options
to \s-1AWK\s0 application and follows rules from
\&\s-1SUS/POSIX \s0\*(L"Utility Syntax Guidelines\*(R"
.PP
power_getopt.awk analyses '.begin\-str help/.end\-str' section in
\&\s-1AWK\s0 program (main module), and processes options specified there.
The following strings mean options:
 \-X             single letter option
 \-\-XXX          long option
 \-X|\-\-XXX       single letter option with long synonym
 =X             single letter option with argument
 =\-XXX          long option with argument
 =X|\-\-XXX       single letter option and long synonym with argument
.PP
If \-\-help option was applied, usage information is printed
(lines between \*(L".begin\-str help\*(R" and \*(L".end\-str\*(R") replacing leading
`=' character with `\-'.
.IP "\fIgetarg(\s-1OPT, DEFAULT\s0)\fR" 2
.IX Item "getarg(OPT, DEFAULT)"
returns either 1 (option \s-1OPT\s0 was applied) or 0 (\s-1OPT\s0 was not
applied) for options not accepting the argument, and either
specified value or \s-1DEFAULT\s0 for options accepting the argument.
.Sp
See example/demo_power_getopt for the sample of usage
.SS "quicksort.awk"
.IX Subsection "quicksort.awk"
.IP "\fIquicksort (src_array, dest_remap, start, end)\fR" 2
.IX Item "quicksort (src_array, dest_remap, start, end)"
The content of `src_array' is sorted using awk's rules for
comparing values. Values with indices in range [start, end] are
sorted.  `src_array' array is not changed.
Instead dest_remap array is generated such that
.Sp
.Vb 5
\&  Result:
\&    src_array [dest_remap [start]] <=
\&       <= src_array [dest_remap [start+1]] <=
\&       <= src_array [dest_remap [start+2]] <= ... <=
\&       <= src_array [dest_remap [end]]
.Ve
.Sp
`quicksort' algorithm is used.
Examples: see demo_quicksort and demo_quicksort2 executables
.IP "\fIquicksort_values (src_hash, dest_remap)\fR" 2
.IX Item "quicksort_values (src_hash, dest_remap)"
The same as `quicksort' described above, but hash values are sorted.
.Sp
.Vb 5
\&  Result: 
\&    src_hash [dest_remap [1]] <=
\&       <= src_hash [dest_remap [2]] <=
\&       <= src_hash [dest_remap [3]] <= ... <=
\&       <= src_hash [dest_remap [count]]
.Ve
.Sp
`count', a number of elements in `src_hash', is a return value.
Examples: see demo_quicksort* executables.
.IP "\fIquicksort_indices (src_hash, dest_remap)\fR" 2
.IX Item "quicksort_indices (src_hash, dest_remap)"
The same as `quicksort' described above, but hash indices are sorted.
.Sp
.Vb 5
\&  Result:
\&    dest_remap [1] <=
\&       <= dest_remap [2] <=
\&       <= dest_remap [3] <= ... <=
\&       <= dest_remap [count]
.Ve
.Sp
`count', a number of elements in `src_hash', is a return value.
.SS "readfile.awk"
.IX Subsection "readfile.awk"
.IP "\fIreadfile(\s-1FILENAME\s0)\fR" 2
.IX Item "readfile(FILENAME)"
read entire file and return its content as a string
.PP
See example/demo_readfile for the sample of usage
.SS "runcmd.awk"
.IX Subsection "runcmd.awk"
.IP "\fIruncmd1 (\s-1CMD, OPTS, FILE\s0)\fR" 2
.IX Item "runcmd1 (CMD, OPTS, FILE)"
wrapper for \fIsystem()\fR function
that runs a command \s-1CMD\s0 with options \s-1OPTS\s0 and one filename \s-1FILE.\s0
Unlike system(\s-1CMD \*(L" \*(R" OPTS \*(L" \*(R" FILE\s0) the function runcmd1 handles
correctly \s-1FILE\s0 containing spaces, single quote, double quote,
tilde etc.
.IP "\fIxruncmd1 (\s-1FILE\s0)\fR" 2
.IX Item "xruncmd1 (FILE)"
safe wrapper for 'runcmd1'.
awk exits with error if \fIruncmd1()\fR function failed.
.SS "shquote.awk"
.IX Subsection "shquote.awk"
.IP "\fIshquote(str)\fR" 2
.IX Item "shquote(str)"
transforms the string `str' by adding shell escape and
quoting characters to include it to the \fIsystem()\fR and \fIpopen()\fR
functions as an argument, so that the arguments will have the
correct values after being evaluated by the shell.
.Sp
For example:
     print shquote(\*(L"file name.txt\*(R")
     |\- 'file name.txt'
     print shquote(\*(L"'\*(R")
     |\- \e'
     print shquote(\*(L"Peter's\*(R")
     |\- 'Peter'\e''s'
     print shquote(\*(L"*&;<>#~\*(R")
     |\- '*&;<>#~'
.PP
This module was inspired by NetBSD \fIshquote\fR\|(3)
   http://netbsd.gw.com/cgi\-bin/man\-cgi?shquote+3+NetBSD\-current
and \fIshquote\fR\|(1) by Alan Barrett
   http://ftp.sunet.se/pub/os/NetBSD/misc/apb/shquote.20080906/
.SS "sort.awk"
.IX Subsection "sort.awk"
.IP "\fIsort (src, dest_remap, start, end)\fR" 2
.IX Item "sort (src, dest_remap, start, end)"
Call either heapsort function from heapsort.awk (if
\&\s-1RUNAWK_SORTTYPE\s0 environment variable is \*(L"heapsort\*(R") or quicksort
from quicksort.awk (if \s-1RUNAWK_SORTTYPE\s0 is \*(L"quicksort\*(R").
Sorttype defaults to \*(L"heapsort\*(R".
.IP "\fIsort_values (src, dest_remap)\fR" 2
.IX Item "sort_values (src, dest_remap)"
Call either heapsort_values function from heapsort.awk (if
\&\s-1RUNAWK_SORTTYPE\s0 environment variable is \*(L"heapsort\*(R") or
quicksort_values from quicksort.awk (if \s-1RUNAWK_SORTTYPE\s0 is
\&\*(L"quicksort\*(R").  Sorttype defaults to \*(L"heapsort\*(R".
.IP "\fIsort_indices (src, dest_remap)\fR" 2
.IX Item "sort_indices (src, dest_remap)"
Call either heapsort_indices function from heapsort.awk (if
\&\s-1RUNAWK_SORTTYPE\s0 environment variable is \*(L"heapsort\*(R") or
quicksort_indices from quicksort.awk (if \s-1RUNAWK_SORTTYPE\s0 is
\&\*(L"quicksort\*(R").  Sorttype defaults to \*(L"heapsort\*(R".
.SS "str2regexp.awk"
.IX Subsection "str2regexp.awk"
.IP "\fIstr2regex(\s-1STRING\s0)\fR" 2
.IX Item "str2regex(STRING)"
returns a regular expression that matches given \s-1STRING\s0
.PP
For example:
  print str2regexp(\*(L"all special symbols: ^$(){}[].*+?|\e\e\*(R")
  \-| all special symbols: [^][$][(][)][{][}][[]\e][.][*][+][?][|]\e\e
.SS "tmpfile.awk"
.IX Subsection "tmpfile.awk"
This module provides a function `tmpfile' for generating temporary
filenames. All these filenames are under temporary directory created
(if necessary) by \fIrunawk\fR\|(1) which is removed automatically during
normal exit or when \fIrunawk\fR\|(1) reveives \s-1SIGINT, SIGQUIT, SIGTERM,
SIGHUP\s0 or \s-1SIGPIPE.\s0
.IP "\fI\fItmpfile()\fI\fR" 2
.IX Item "tmpfile()"
returns a temporary file name.
.IP "\fIrunawk_tmpdir\fR" 2
.IX Item "runawk_tmpdir"
global variable that keeps tempdir created by runawk \-t
.PP
See example/demo_tmpfile for the sample of usage
.SS "tokenre.awk"
.IX Subsection "tokenre.awk"
By default \s-1AWK\s0 splits input lines into tokens according to regular
expression that defines \*(L"spaces\*(R" between tokens using special
variable \s-1FS.\s0 In many situations it is more useful to define regular
expressions for tokens themselves. This is what this module does.
.IP "\fItokenre(\s-1STRING, REGEXP\s0)\fR" 2
.IX Item "tokenre(STRING, REGEXP)"
extracts substrings from \s-1STRING\s0
according to \s-1REGEXP\s0 from the left to the right and assigns \f(CW$1\fR, \f(CW$2\fR
etc. and \s-1NF\s0 variable.
.IP "\fItokenre0(\s-1REGEXP\s0)\fR" 2
.IX Item "tokenre0(REGEXP)"
Does the the same as `tokenre' but splits \f(CW$0\fR instead.
.IP "\fIsplitre(\s-1STRING, ARR, REGEXP\s0)\fR" 2
.IX Item "splitre(STRING, ARR, REGEXP)"
The same as `tokenre' but ARR[1], ARR[2]... are assigned.
A number of extracted tokens is a return value.
.IP "\fI\s-1TRE\s0\fR" 2
.IX Item "TRE"
global variable. If it is set to non-empty string, all input
lines are split automatically.
.SS "trim.awk"
.IX Subsection "trim.awk"
.IP "\fItrim_l(\s-1STRING\s0)\fR" 2
.IX Item "trim_l(STRING)"
Removes leading Tab and Space characters from \s-1STRING\s0 and returns
the result.
.IP "\fItrim_r(\s-1STRING\s0)\fR" 2
.IX Item "trim_r(STRING)"
Removes Tab and Space characters at the end of \s-1STRING\s0 and returns
the result.
.IP "\fItrim_c(\s-1STRING, REPL\s0)\fR" 2
.IX Item "trim_c(STRING, REPL)"
Replaces sequences of Tab and Space characters in \s-1STRING\s0 with \s-1REPL\s0
and returns the result. If \s-1REPL\s0 is not specified, it defaults to
single Space character.
.IP "\fItrim_lr(\s-1STRING\s0)\fR" 2
.IX Item "trim_lr(STRING)"
Equal to trim_l(trim_r(\s-1STRING\s0))
.IP "\fItrim_lrc(\s-1STRING, REPL\s0)\fR" 2
.IX Item "trim_lrc(STRING, REPL)"
Equal to trim_l(trim_r(trim_c(\s-1STRING, REPL\s0)))
.PP
See example/demo_trim for the sample of usage
.SS "trim_in.awk"
.IX Subsection "trim_in.awk"
As the name of this module says (_in suffix) this module reads and
potentially changes input lines.
.PP
Leading, ending spaces and/or spaces in the middle of input lines
are removed depending on \s-1TRIM\s0 variable.
\&\s-1TRIM\s0 values:
  \*(L"l\*(R" \- remove leading space characters
  \*(L"r\*(R" \- remove ending space characters
  \*(L"c\*(R" \- remove extra space characters in the middle of input lines
  \*(L"lr\*(R" \- See l and r
  \*(L"lrc\*(R" \- See l, r and c
  \*(L"lc\*(R" \- See l and c
  \*(L"cr\*(R" \- See c and r
By default \s-1TRIM\s0 variable is set to \*(L"lr\*(R". \s-1TRIM\s0 set to a single space
character means no trimming.
.SS "xclose.awk"
.IX Subsection "xclose.awk"
.IP "\fIxclose(\s-1FILE\s0)\fR" 2
.IX Item "xclose(FILE)"
safe wrapper for 'close'.
awk exits with error if \fIclose()\fR function failed.
.SS "xgetline.awk"
.IX Subsection "xgetline.awk"
.IP "\fIxgetline0([\s-1FILE\s0])\fR" 2
.IX Item "xgetline0([FILE])"
Safe analog to 'getline < \s-1FILE\s0' or 'getline' (if no \s-1FILE\s0 is specified).
0 at the end means that input line is assigned to \f(CW$0\fR.
.IP "\fIxgetline([\s-1FILE\s0])\fR" 2
.IX Item "xgetline([FILE])"
Safe analog to 'getline _\|_input < \s-1FILE\s0' and 'getline _\|_input'
(if no \s-1FILE\s0 is specified)
.PP
In both cases \*(L"safe\*(R" means that returned value is analysed and
if it is less than zero (file reading error happens) program will
be terminated emmidiately with appropriate error message sent to stderr.
Both functions return zero if end of file is reached or non-zero otherwise.
.PP
Example:
      while (xgetline(\*(L"/etc/passwd\*(R")){
          print \*(L"user: \*(R" _\|_input
      }
.SS "xsystem.awk"
.IX Subsection "xsystem.awk"
.IP "\fIxsystem(\s-1FILE\s0)\fR" 2
.IX Item "xsystem(FILE)"
safe wrapper for 'system'.
awk exits with error if \fIsystem()\fR function failed.
.SS "ord.awk"
.IX Subsection "ord.awk"
.IP "\fIord (\s-1CHAR\s0)\fR" 2
.IX Item "ord (CHAR)"
return numeral code of \s-1CHAR\s0
.IP "\fIchr (\s-1CODE\s0)\fR" 2
.IX Item "chr (CODE)"
return symbol from the \s-1CODE\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2007\-2014 Aleksey Cheusov <vle@gmx.net>
.SH "BUGS/FEEDBACK"
.IX Header "BUGS/FEEDBACK"
Please send any comments, questions, bug reports etc. to me by e\-mail
or register them at sourceforge project home.  Feature requests are
also welcomed.
.SH "HOME"
.IX Header "HOME"
<http://sourceforge.net/projects/runawk/>
.SH "SEE ALSO \fIawk\fP\|(1)"
.IX Header "SEE ALSO awk"