| runawk_modules(3) | runawk_modules(3) |
runawk - wrapper for AWK interpreter
runawk provides dozens of modules. Below is the documentation for them.
As the name of this module says (_in suffix) this module reads and optionally changes input lines.
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
#use "CR_in.awk"
in the very beginning of your script.
NOTE: alt_getopt.awk module follows rules from SUS/POSIX "Utility Syntax Guidelines"
As the name of this module (_in suffix) says this module reads and optionally changes input lines.
Backslash character at the end of line is treated as a sign that current line is continued on the next one. Example is below.
Input:
a b c\
d e f g
a
b
e\
f
What your program using backslash_in.awk will obtain:
a b cd e f g
a
b
e f
See example/demo_basename for the sample of usage
For example: print
braceexpand("ab{,22{,7,8}}z{8,9}")
-| abz8 abz9 ab22z8 ab22z9 ab227z8 ab227z9 ab228z8 ab228z9
See example/demo_dirname for the sample of usage
This module reads a program's file, find .begin-str/.end-str pairs and reads lines between them.
EMBED_STR - Associative array with string index
Example:
Input:
.begin-str mymsg
Line1
Line2
.end-str
Output (result)
EMBED_STR ["mymsg"]="Line1\nLine2"
See example/demo_embed_str for the sample of usage
By default AWK interpreter splits input lines into tokens according to regular expression that defines "spaces" between them using special variable FS. 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 GNU awk's FIELDWIDTHS variable.
See example/demo_fieldwidths for the sample of usage
beginfile() function provided by user is called before file reading
endfile() function provided by user is called after file reading
See example/demo_has_prefix for the sample of usage
See example/demo_has_suffix for the sample of usage
Result:
src_array [dest_remap [start]] <=
<= src_array [dest_remap [start+1]] <=
<= src_array [dest_remap [start+2]] <= ... <=
<= src_array [dest_remap [end]]
`heapsort' algorithm is used.
Examples: see demo_heapsort and demo_heapsort2 executables.
Result:
src_array [dest_remap [1]] <=
<= src_array [dest_remap [2]] <=
<= src_array [dest_remap [3]] <= ... <=
<= src_array [dest_remap [count]]
`count', a number of elements in `src_hash', is a return value.
Examples: see demo_heapsort3 executable.
Result:
dest_remap [1] <=
<= dest_remap [2] <=
<= dest_remap [3] <= ... <=
<= dest_remap [count]
`count', a number of elements in `src_hash', is a return value.
Examples: demo_ini
This module provides functions for manipulating .ini files. See example/demo_ini for the sample of use.
Features:
- spaces are allowed everywhere, i.e. at the beginning and end of
line, around `=' separator. THEY ARE STRIPPED!
- comment lines start with `;' or `#' 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?).
Initialization step for power_getopt.awk module. In some cases it makes sense to process options in a while() loop. This module allows doing this. See the documentation about how options are initialized in power_getopt.awk module.
This module provides a number of IO functions.
Return value:
-2 if file doesn't exist
-1 if file is not a regular file
filesize otherwise
Return value:
- -- regular file
d -- directory
c -- character device
b -- block device
p -- FIFO
l -- symlink
s -- socket
See example/demo_io for the sample of usage
For example:
print match_br("A (B (), C(D,C,F (), 123))", "(",
")")
print RSTART, RLENGTH
-| 3
-| 3
-| 24
This module provides the following variables
See example/demo_modinfo for the sample of usage
For example:
print multisub("ABBABBBBBBAAB", "ABB:c BBA:d AB:e")
|- ccBBde
power_getopt.awk module provides a very easy way to add options to AWK application and follows rules from SUS/POSIX "Utility Syntax Guidelines"
power_getopt.awk analyses '.begin-str help/.end-str' section in
AWK 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
If --help option was applied, usage information is printed (lines between ".begin-str help" and ".end-str") replacing leading `=' character with `-'.
See example/demo_power_getopt for the sample of usage
Result:
src_array [dest_remap [start]] <=
<= src_array [dest_remap [start+1]] <=
<= src_array [dest_remap [start+2]] <= ... <=
<= src_array [dest_remap [end]]
`quicksort' algorithm is used. Examples: see demo_quicksort and demo_quicksort2 executables
Result:
src_hash [dest_remap [1]] <=
<= src_hash [dest_remap [2]] <=
<= src_hash [dest_remap [3]] <= ... <=
<= src_hash [dest_remap [count]]
`count', a number of elements in `src_hash', is a return value. Examples: see demo_quicksort* executables.
Result:
dest_remap [1] <=
<= dest_remap [2] <=
<= dest_remap [3] <= ... <=
<= dest_remap [count]
`count', a number of elements in `src_hash', is a return value.
See example/demo_readfile for the sample of usage
For example:
print shquote("file name.txt")
|- 'file name.txt'
print shquote("'")
|- \'
print shquote("Peter's")
|- 'Peter'\''s'
print shquote("*&;<>#~")
|- '*&;<>#~'
This module was inspired by NetBSD shquote(3)
http://netbsd.gw.com/cgi-bin/man-cgi?shquote+3+NetBSD-current and
shquote(1) by Alan Barrett
http://ftp.sunet.se/pub/os/NetBSD/misc/apb/shquote.20080906/
For example:
print str2regexp("all special symbols: ^$(){}[].*+?|\\")
-| all special symbols: [^][$][(][)][{][}][[]\][.][*][+][?][|]\\
This module provides a function `tmpfile' for generating temporary filenames. All these filenames are under temporary directory created (if necessary) by runawk(1) which is removed automatically during normal exit or when runawk(1) reveives SIGINT, SIGQUIT, SIGTERM, SIGHUP or SIGPIPE.
See example/demo_tmpfile for the sample of usage
By default AWK splits input lines into tokens according to regular expression that defines "spaces" between tokens using special variable FS. In many situations it is more useful to define regular expressions for tokens themselves. This is what this module does.
See example/demo_trim for the sample of usage
As the name of this module says (_in suffix) this module reads and potentially changes input lines.
Leading, ending spaces and/or spaces in the middle of input lines
are removed depending on TRIM variable. TRIM values:
"l" - remove leading space characters
"r" - remove ending space characters
"c" - remove extra space characters in the middle of input lines
"lr" - See l and r
"lrc" - See l, r and c
"lc" - See l and c
"cr" - See c and r By default TRIM variable is set to
"lr". TRIM set to a single space character means no trimming.
In both cases "safe" 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.
Example:
while (xgetline("/etc/passwd")){
print "user: " __input
}
Copyright (c) 2007-2014 Aleksey Cheusov <vle@gmx.net>
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.
<http://sourceforge.net/projects/runawk/>
| 2023-01-02 |