[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, feature/api-parser, updated. gawk-4.1.0-
|
From: |
Andrew J. Schorr |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, feature/api-parser, updated. gawk-4.1.0-2489-g7f6772a |
|
Date: |
Mon, 10 Apr 2017 11:57:37 -0400 (EDT) |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, feature/api-parser has been updated
via 7f6772a66e57c9f636cbbf370015200a7dae2ef8 (commit)
from 215618921d2515040bd02fecc1a3438cd4949a5b (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=7f6772a66e57c9f636cbbf370015200a7dae2ef8
commit 7f6772a66e57c9f636cbbf370015200a7dae2ef8
Author: Andrew J. Schorr <address@hidden>
Date: Mon Apr 10 11:57:07 2017 -0400
Update texinfo docs to document new FIELDWIDTHS and API input parser
capabilities.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 6e5d1a7..7b956c4 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+2017-04-10 Andrew J. Schorr <address@hidden>
+
+ * gawktexi.in: Document FIELDWIDTHS enhancement to support an optional
+ field skip prefix. Document new PROCINFO["FS"] value "API".
+ Document new get_record field_width argument that enables the API
+ parser to override the default field parsing mechanism.
+
2017-04-07 Arnold D. Robbins <address@hidden>
* using-git.texi: Removed.
diff --git a/doc/gawk.info b/doc/gawk.info
index 197dc2f..d33e018 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -5127,9 +5127,12 @@ by assigning a string containing space-separated numbers
to the built-in
variable 'FIELDWIDTHS'. Each number specifies the width of the field,
_including_ columns between fields. If you want to ignore the columns
between fields, you can specify the width as a separate field that is
-subsequently ignored. It is a fatal error to supply a field width that
-has a negative value. The following data is the output of the Unix 'w'
-utility. It is useful to illustrate the use of 'FIELDWIDTHS':
+subsequently ignored. Or, starting in version 4.2, each field width may
+optionally be preceded by a colon-separated value specifying the number
+of characters to skip before the field starts. It is a fatal error to
+supply a field width that has a negative value. The following data is
+the output of the Unix 'w' utility. It is useful to illustrate the use
+of 'FIELDWIDTHS':
10:06pm up 21 days, 14:04, 23 users
User tty login idle JCPU PCPU what
@@ -5176,6 +5179,20 @@ calculated idle time:
brent ttyp0 286
dave ttyq4 1296000
+ Starting in version 4.2, this program could be rewritten to specify
+'FIELDWIDTHS' like so:
+ BEGIN { FIELDWIDTHS = "8 1:5 4:7 6 1:6 1:6 2:33" }
+ This strips away some of the white space separating the fields. With
+such a change, the program would produce the following results:
+
+ hzang ttyV3 50
+ eklye ttyV5 0
+ dportein ttyV6 107
+ gierd ttyD3 1
+ dave ttyD4 0
+ brent ttyp0 286
+ dave ttyq4 1296000
+
Another (possibly more practical) example of fixed-width input data
is the input from a deck of balloting cards. In some parts of the
United States, voters mark their choices by punching holes in computer
@@ -5197,8 +5214,10 @@ value is '"FS"' if regular field splitting is being
used, or
REGULAR FIELD SPLITTING ...
else if (PROCINFO["FS"] == "FIELDWIDTHS")
FIXED-WIDTH FIELD SPLITTING ...
- else
+ else if (PROCINFO["FS"] == "FPAT")
CONTENT-BASED FIELD SPLITTING ... (see next minor node)
+ else
+ API INPUT PARSER FIELD SPLITTING ... (*note Input Parsers::)
This information is useful when writing a function that needs to
temporarily change 'FS' or 'FIELDWIDTHS', read some records, and then
@@ -5304,7 +5323,10 @@ available for splitting regular strings (*note String
Functions::).
To recap, 'gawk' provides three independent methods to split input
records into fields. The mechanism used is based on which of the three
-variables--'FS', 'FIELDWIDTHS', or 'FPAT'--was last assigned to.
+variables--'FS', 'FIELDWIDTHS', or 'FPAT'--was last assigned to. In
+addition, an API input parser may choose to override the record parsing
+mechanism; please refer to *note Input Parsers:: for further information
+about this feature.
---------- Footnotes ----------
@@ -10441,9 +10463,12 @@ each variable.)
'FIELDWIDTHS #'
A space-separated list of columns that tells 'gawk' how to split
- input with fixed columnar boundaries. Assigning a value to
- 'FIELDWIDTHS' overrides the use of 'FS' and 'FPAT' for field
- splitting. *Note Constant Size:: for more information.
+ input with fixed columnar boundaries. Starting in version 4.2,
+ each field width may optionally be preceded by a colon-separated
+ value specifying the number of characters to skip before the field
+ starts. Assigning a value to 'FIELDWIDTHS' overrides the use of
+ 'FS' and 'FPAT' for field splitting. *Note Constant Size:: for
+ more information.
'FPAT #'
A regular expression (as a string) that tells 'gawk' to create the
@@ -10727,8 +10752,9 @@ they are not special:
'PROCINFO["FS"]'
This is '"FS"' if field splitting with 'FS' is in effect,
'"FIELDWIDTHS"' if field splitting with 'FIELDWIDTHS' is in
- effect, or '"FPAT"' if field matching with 'FPAT' is in
- effect.
+ effect, '"FPAT"' if field matching with 'FPAT' is in effect,
+ or '"API"' if field splitting is controlled by an API input
+ parser.
'PROCINFO["gid"]'
The value of the 'getgid()' system call.
@@ -24167,7 +24193,8 @@ for 'RT', if any.
#define INVALID_HANDLE (-1)
void *opaque; /* private data for input parsers */
int (*get_record)(char **out, struct awk_input *iobuf,
- int *errcode, char **rt_start, size_t *rt_len);
+ int *errcode, char **rt_start, size_t *rt_len,
+ const awk_fieldwidth_info_t **field_width);
ssize_t (*read_func)();
void (*close_func)(struct awk_input *iobuf);
struct stat sbuf; /* stat buf */
@@ -24213,7 +24240,8 @@ may be filled by 'XXX_take_control_of()':
' struct awk_input *iobuf,'
' int *errcode,'
' char **rt_start,'
-' size_t *rt_len);'
+' size_t *rt_len,'
+' const awk_fieldwidth_info_t **field_width);'
This function pointer should point to a function that creates the
input records. Said function is the core of the input parser. Its
behavior is described in the text following this list.
@@ -24263,6 +24291,20 @@ records. The parameters are as follows:
'*rt_len' should be set to zero. 'gawk' makes its own copy of this
data, so the extension must manage this storage.
+'const awk_fieldwidth_info_t **field_width'
+ If 'field_width' is not 'NULL', then '*field_width' will be
+ initialized to 'NULL', and the function may set it to point to a
+ structure supplying field width information to override the default
+ field parsing mechanism. Note that this structure will not be
+ copied by 'gawk'; it must persist at least until the next call to
+ 'get_record' or 'close_func'. Note also that 'field_width' will be
+ 'NULL' when 'getline' is assigning the results to a variable, thus
+ field parsing is not needed. If the parser does set
+ '*field_width', then 'gawk' will use this layout to parse the input
+ record, and the 'PROCINFO["FS"]' value will be '"API"' while this
+ record is active in '$0'. The 'awk_fieldwidth_info_t' data
+ structure is described below.
+
The return value is the length of the buffer pointed to by '*out', or
'EOF' if end-of-file was reached or an error occurred.
@@ -24312,6 +24354,47 @@ activate an input parser (*note BEGINFILE/ENDFILE::).
'void register_input_parser(awk_input_parser_t *input_parser);'
Register the input parser pointed to by 'input_parser' with 'gawk'.
+ If you would like to override the default field parsing mechanism for
+a given record, then you must populate the 'awk_fieldwidth_info_t'
+structure, which looks like this:
+
+ typedef struct {
+ awk_bool_t use_chars; /* false ==> use bytes */
+ size_t nf; /* number of fields in record (NF) */
+ struct awk_field_info {
+ size_t skip; /* amount to skip before field starts */
+ size_t len; /* length of field */
+ } fields[1]; /* actual dimension should be nf */
+ } awk_fieldwidth_info_t;
+
+ The fields are:
+
+'awk_bool_t use_chars;'
+ Set this to 'awk_true' if the field lengths are specified in terms
+ of potentially multi-byte characters, and set it to 'awk_false' if
+ the lengths are in terms of bytes. Performance will be better if
+ the values are supplied in terms of bytes.
+
+'size_t nf;'
+ Set this to the number of fields in the input record, i.e. 'NF'.
+
+'struct awk_field_info fields[nf];'
+ This is a variable-length array whose actual dimension should be
+ 'nf'. For each field, the 'skip' element should be set to the
+ number of characters or bytes, as controlled by the 'use_chars'
+ flag, to skip before the start of this field. And the 'len'
+ element provides the length of the field. The values in
+ 'fields[0]' provide the information for the '$1' field, and so on
+ through the 'fields[nf-1]' element containing the information for
+ '$NF'.
+
+ A convenience macro 'awk_fieldwidth_info_size(NF)' is provided to
+calculate the appropriate size of a variable-length
+'awk_fieldwidth_info_t' structure containing 'NF' fields. This can be
+used as an argument to 'malloc' or in a union to allocate space
+statically. Please refer to the sample extension 'readdir_test' for an
+example.
+
File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev:
Input Parsers, Up: Registration Functions
@@ -33052,8 +33135,8 @@ Index
* caret (^), ^= operator: Assignment Ops. (line 129)
* caret (^), ^= operator <1>: Precedence. (line 94)
* case keyword: Switch Statement. (line 6)
-* case sensitivity, and regexps: User-modified. (line 76)
-* case sensitivity, and string comparisons: User-modified. (line 76)
+* case sensitivity, and regexps: User-modified. (line 79)
+* case sensitivity, and string comparisons: User-modified. (line 79)
* case sensitivity, array indices and: Array Intro. (line 100)
* case sensitivity, converting case: String Functions. (line 523)
* case sensitivity, example programs: Library Functions. (line 53)
@@ -33242,7 +33325,7 @@ Index
* dark corner, field separators: Full Line Fields. (line 22)
* dark corner, FILENAME variable: Getline Notes. (line 19)
* dark corner, FILENAME variable <1>: Auto-set. (line 108)
-* dark corner, FNR/NR variables: Auto-set. (line 357)
+* dark corner, FNR/NR variables: Auto-set. (line 358)
* dark corner, format-control characters: Control Letters. (line 18)
* dark corner, format-control characters <1>: Control Letters.
(line 93)
@@ -33441,13 +33524,13 @@ Index
* differences in awk and gawk, error messages: Special FD. (line 19)
* differences in awk and gawk, FIELDWIDTHS variable: User-modified.
(line 37)
-* differences in awk and gawk, FPAT variable: User-modified. (line 43)
+* differences in awk and gawk, FPAT variable: User-modified. (line 46)
* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 134)
* differences in awk and gawk, function arguments (gawk): Calling Built-in.
(line 16)
* differences in awk and gawk, getline command: Getline. (line 19)
* differences in awk and gawk, IGNORECASE variable: User-modified.
- (line 76)
+ (line 79)
* differences in awk and gawk, implementation limitations: Getline Notes.
(line 14)
* differences in awk and gawk, implementation limitations <1>: Redirection.
@@ -33460,7 +33543,7 @@ Index
(line 96)
* differences in awk and gawk, line continuations: Conditional Exp.
(line 34)
-* differences in awk and gawk, LINT variable: User-modified. (line 87)
+* differences in awk and gawk, LINT variable: User-modified. (line 90)
* differences in awk and gawk, match() function: String Functions.
(line 262)
* differences in awk and gawk, print/printf statements: Format Modifiers.
@@ -33477,7 +33560,7 @@ Index
(line 6)
* differences in awk and gawk, RS/RT variables: gawk split records.
(line 58)
-* differences in awk and gawk, RT variable: Auto-set. (line 295)
+* differences in awk and gawk, RT variable: Auto-set. (line 296)
* differences in awk and gawk, single-character fields: Single Character
Fields.
(line 6)
* differences in awk and gawk, split() function: String Functions.
@@ -33485,9 +33568,9 @@ Index
* differences in awk and gawk, strings: Scalar Constants. (line 20)
* differences in awk and gawk, strings, storing: gawk split records.
(line 76)
-* differences in awk and gawk, SYMTAB variable: Auto-set. (line 299)
+* differences in awk and gawk, SYMTAB variable: Auto-set. (line 300)
* differences in awk and gawk, TEXTDOMAIN variable: User-modified.
- (line 152)
+ (line 155)
* differences in awk and gawk, trunc-mod operation: Arithmetic Ops.
(line 66)
* directories, command-line: Command-line directories.
@@ -33648,7 +33731,7 @@ Index
(line 6)
* extension API version: Extension Versioning.
(line 6)
-* extension API, version number: Auto-set. (line 246)
+* extension API, version number: Auto-set. (line 247)
* extension example: Extension Example. (line 6)
* extension registration: Registration Functions.
(line 6)
@@ -33699,11 +33782,11 @@ Index
(line 6)
* field separator, POSIX and: Full Line Fields. (line 16)
* field separators: Field Separators. (line 15)
-* field separators <1>: User-modified. (line 50)
-* field separators <2>: User-modified. (line 113)
+* field separators <1>: User-modified. (line 53)
+* field separators <2>: User-modified. (line 116)
* field separators, choice of: Field Separators. (line 50)
* field separators, FIELDWIDTHS variable and: User-modified. (line 37)
-* field separators, FPAT variable and: User-modified. (line 43)
+* field separators, FPAT variable and: User-modified. (line 46)
* field separators, regular expressions as: Field Separators. (line 50)
* field separators, regular expressions as <1>: Regexp Field Splitting.
(line 6)
@@ -33800,7 +33883,7 @@ Index
(line 12)
* FNR variable: Records. (line 6)
* FNR variable <1>: Auto-set. (line 118)
-* FNR variable, changing: Auto-set. (line 357)
+* FNR variable, changing: Auto-set. (line 358)
* for statement: For Statement. (line 6)
* for statement, looping over arrays: Scanning an Array. (line 20)
* fork() extension function: Extension Sample Fork.
@@ -33824,7 +33907,7 @@ Index
* forward slash (/), patterns and: Expression Patterns. (line 24)
* FPAT variable: Splitting By Content.
(line 25)
-* FPAT variable <1>: User-modified. (line 43)
+* FPAT variable <1>: User-modified. (line 46)
* frame debugger command: Execution Stack. (line 27)
* Free Documentation License (FDL): GNU Free Documentation License.
(line 8)
@@ -33834,7 +33917,7 @@ Index
* Free Software Foundation (FSF) <3>: Glossary. (line 405)
* FreeBSD: Glossary. (line 748)
* FS variable: Field Separators. (line 15)
-* FS variable <1>: User-modified. (line 50)
+* FS variable <1>: User-modified. (line 53)
* FS variable, --field-separator option and: Options. (line 21)
* FS variable, as null string: Single Character Fields.
(line 20)
@@ -33904,7 +33987,7 @@ Index
* G., Daniel Richard <1>: Maintainers. (line 14)
* Garfinkle, Scott: Contributors. (line 35)
* gawk program, dynamic profiling: Profiling. (line 177)
-* gawk version: Auto-set. (line 221)
+* gawk version: Auto-set. (line 222)
* gawk, ARGIND variable in: Other Arguments. (line 15)
* gawk, awk and: Preface. (line 21)
* gawk, awk and <1>: This Manual. (line 14)
@@ -33931,7 +34014,7 @@ Index
* gawk, extensions, disabling: Options. (line 257)
* gawk, features, adding: Adding Code. (line 6)
* gawk, features, advanced: Advanced Features. (line 6)
-* gawk, field separators and: User-modified. (line 71)
+* gawk, field separators and: User-modified. (line 74)
* gawk, FIELDWIDTHS variable in: Constant Size. (line 22)
* gawk, FIELDWIDTHS variable in <1>: User-modified. (line 37)
* gawk, file names in: Special Files. (line 6)
@@ -33939,12 +34022,12 @@ Index
* gawk, format-control characters <1>: Control Letters. (line 93)
* gawk, FPAT variable in: Splitting By Content.
(line 25)
-* gawk, FPAT variable in <1>: User-modified. (line 43)
+* gawk, FPAT variable in <1>: User-modified. (line 46)
* gawk, FUNCTAB array in: Auto-set. (line 134)
* gawk, function arguments and: Calling Built-in. (line 16)
* gawk, hexadecimal numbers and: Nondecimal-numbers. (line 41)
* gawk, IGNORECASE variable in: Case-sensitivity. (line 26)
-* gawk, IGNORECASE variable in <1>: User-modified. (line 76)
+* gawk, IGNORECASE variable in <1>: User-modified. (line 79)
* gawk, IGNORECASE variable in <2>: Array Intro. (line 100)
* gawk, IGNORECASE variable in <3>: String Functions. (line 58)
* gawk, IGNORECASE variable in <4>: Array Sorting Functions.
@@ -33962,7 +34045,7 @@ Index
(line 6)
* gawk, interval expressions and: Regexp Operators. (line 139)
* gawk, line continuation in: Conditional Exp. (line 34)
-* gawk, LINT variable in: User-modified. (line 87)
+* gawk, LINT variable in: User-modified. (line 90)
* gawk, list of contributors to: Contributors. (line 6)
* gawk, MS-Windows version of: PC Using. (line 9)
* gawk, newlines in: Statements/Lines. (line 12)
@@ -33980,13 +34063,13 @@ Index
* gawk, regular expressions, precedence: Regexp Operators. (line 161)
* gawk, RT variable in: awk split records. (line 124)
* gawk, RT variable in <1>: Multiple Line. (line 130)
-* gawk, RT variable in <2>: Auto-set. (line 295)
+* gawk, RT variable in <2>: Auto-set. (line 296)
* gawk, See Also awk: Preface. (line 34)
* gawk, source code, obtaining: Getting. (line 6)
-* gawk, splitting fields and: Constant Size. (line 86)
+* gawk, splitting fields and: Constant Size. (line 103)
* gawk, string-translation functions: I18N Functions. (line 6)
-* gawk, SYMTAB array in: Auto-set. (line 299)
-* gawk, TEXTDOMAIN variable in: User-modified. (line 152)
+* gawk, SYMTAB array in: Auto-set. (line 300)
+* gawk, TEXTDOMAIN variable in: User-modified. (line 155)
* gawk, timestamps: Time Functions. (line 6)
* gawk, uses for: Preface. (line 34)
* gawk, versions of, information about, printing: Options. (line 304)
@@ -34082,7 +34165,7 @@ Index
* Grigera, Juan: Contributors. (line 58)
* group database, reading: Group Functions. (line 6)
* group file: Group Functions. (line 6)
-* group ID of gawk user: Auto-set. (line 170)
+* group ID of gawk user: Auto-set. (line 171)
* groups, information about: Group Functions. (line 6)
* gsub: Standard Regexp Constants.
(line 43)
@@ -34122,7 +34205,7 @@ Index
* igawk.sh program: Igawk Program. (line 124)
* ignore breakpoint: Breakpoint Control. (line 87)
* ignore debugger command: Breakpoint Control. (line 87)
-* IGNORECASE variable: User-modified. (line 76)
+* IGNORECASE variable: User-modified. (line 79)
* IGNORECASE variable, and array indices: Array Intro. (line 100)
* IGNORECASE variable, and array sorting functions: Array Sorting Functions.
(line 83)
@@ -34197,7 +34280,7 @@ Index
* interacting with other programs: I/O Functions. (line 107)
* internationalization: I18N Functions. (line 6)
* internationalization <1>: I18N and L10N. (line 6)
-* internationalization, localization: User-modified. (line 152)
+* internationalization, localization: User-modified. (line 155)
* internationalization, localization <1>: Internationalization.
(line 13)
* internationalization, localization, character classes: Bracket Expressions.
@@ -34310,7 +34393,7 @@ Index
* lines, duplicate, removing: History Sorting. (line 6)
* lines, matching ranges of: Ranges. (line 6)
* lines, skipping between markers: Ranges. (line 43)
-* lint checking: User-modified. (line 87)
+* lint checking: User-modified. (line 90)
* lint checking, array elements: Delete. (line 34)
* lint checking, array subscripts: Uninitialized Subscripts.
(line 43)
@@ -34320,7 +34403,7 @@ Index
(line 343)
* lint checking, undefined functions: Pass By Value/Reference.
(line 85)
-* LINT variable: User-modified. (line 87)
+* LINT variable: User-modified. (line 90)
* Linux: Manual History. (line 28)
* Linux <1>: I18N Example. (line 57)
* Linux <2>: Glossary. (line 748)
@@ -34382,7 +34465,7 @@ Index
* mawk utility <2>: Concatenation. (line 36)
* mawk utility <3>: Nextfile Statement. (line 47)
* mawk utility <4>: Other Versions. (line 48)
-* maximum precision supported by MPFR library: Auto-set. (line 235)
+* maximum precision supported by MPFR library: Auto-set. (line 236)
* McIlroy, Doug: Glossary. (line 257)
* McPhee, Patrick: Contributors. (line 101)
* message object files: Explaining gettext. (line 42)
@@ -34395,7 +34478,7 @@ Index
* messages from extensions: Printing Messages. (line 6)
* metacharacters in regular expressions: Regexp Operators. (line 6)
* metacharacters, escape sequences for: Escape Sequences. (line 140)
-* minimum precision required by MPFR library: Auto-set. (line 238)
+* minimum precision required by MPFR library: Auto-set. (line 239)
* mktime: Time Functions. (line 25)
* modifiers, in format specifiers: Format Modifiers. (line 6)
* monetary information, localization: Explaining gettext. (line 104)
@@ -34453,7 +34536,7 @@ Index
* not Boolean-logic operator: Boolean Ops. (line 6)
* NR variable: Records. (line 6)
* NR variable <1>: Auto-set. (line 143)
-* NR variable, changing: Auto-set. (line 357)
+* NR variable, changing: Auto-set. (line 358)
* null strings: awk split records. (line 114)
* null strings <1>: Regexp Field Splitting.
(line 43)
@@ -34479,7 +34562,7 @@ Index
* numbers, converting: Strings And Numbers. (line 6)
* numbers, converting <1>: Bitwise Functions. (line 108)
* numbers, converting, to strings: User-modified. (line 30)
-* numbers, converting, to strings <1>: User-modified. (line 104)
+* numbers, converting, to strings <1>: User-modified. (line 107)
* numbers, hexadecimal: Nondecimal-numbers. (line 6)
* numbers, octal: Nondecimal-numbers. (line 6)
* numbers, rounding: Round Function. (line 6)
@@ -34493,11 +34576,11 @@ Index
* octal values, enabling interpretation of: Options. (line 209)
* OFMT variable: OFMT. (line 15)
* OFMT variable <1>: Strings And Numbers. (line 56)
-* OFMT variable <2>: User-modified. (line 104)
+* OFMT variable <2>: User-modified. (line 107)
* OFMT variable, POSIX awk and: OFMT. (line 27)
* OFS variable: Changing Fields. (line 64)
* OFS variable <1>: Output Separators. (line 6)
-* OFS variable <2>: User-modified. (line 113)
+* OFS variable <2>: User-modified. (line 116)
* OpenBSD: Glossary. (line 748)
* OpenSolaris: Other Versions. (line 100)
* operating systems, BSD-based: Manual History. (line 28)
@@ -34553,7 +34636,7 @@ Index
* ord() user-defined function: Ordinal Functions. (line 16)
* order of evaluation, concatenation: Concatenation. (line 41)
* ORS variable: Output Separators. (line 20)
-* ORS variable <1>: User-modified. (line 119)
+* ORS variable <1>: User-modified. (line 122)
* output field separator, See OFS variable: Changing Fields. (line 64)
* output record separator, See ORS variable: Output Separators.
(line 20)
@@ -34573,7 +34656,7 @@ Index
* p debugger command (alias for print): Viewing And Changing Data.
(line 35)
* Papadopoulos, Panos: Contributors. (line 129)
-* parent process ID of gawk process: Auto-set. (line 210)
+* parent process ID of gawk process: Auto-set. (line 211)
* parentheses (), in a profile: Profiling. (line 146)
* parentheses (), regexp operator: Regexp Operators. (line 81)
* password file: Passwd Functions. (line 16)
@@ -34696,7 +34779,7 @@ Index
* POSIX, gawk extensions not included in: POSIX/GNU. (line 6)
* POSIX, programs, implementing in awk: Clones. (line 6)
* POSIXLY_CORRECT environment variable: Options. (line 343)
-* PREC variable: User-modified. (line 124)
+* PREC variable: User-modified. (line 127)
* precedence: Increment Ops. (line 60)
* precedence <1>: Precedence. (line 6)
* precedence, regexp operators: Regexp Operators. (line 156)
@@ -34711,7 +34794,7 @@ Index
* print statement, commas, omitting: Print Examples. (line 30)
* print statement, I/O operators in: Precedence. (line 70)
* print statement, line continuations and: Print Examples. (line 75)
-* print statement, OFMT variable and: User-modified. (line 113)
+* print statement, OFMT variable and: User-modified. (line 116)
* print statement, See Also redirection, of output: Redirection.
(line 17)
* print statement, sprintf() function and: Round Function. (line 6)
@@ -34742,8 +34825,8 @@ Index
* printing, unduplicated lines of text: Uniq Program. (line 6)
* printing, user information: Id Program. (line 6)
* private variables: Library Names. (line 11)
-* process group ID of gawk process: Auto-set. (line 204)
-* process ID of gawk process: Auto-set. (line 207)
+* process group ID of gawk process: Auto-set. (line 205)
+* process ID of gawk process: Auto-set. (line 208)
* processes, two-way communications with: Two-way I/O. (line 6)
* processing data: Basic High Level. (line 6)
* PROCINFO array: Auto-set. (line 148)
@@ -34758,7 +34841,7 @@ Index
(line 26)
* profiling awk programs: Profiling. (line 6)
* profiling awk programs, dynamically: Profiling. (line 177)
-* program identifiers: Auto-set. (line 173)
+* program identifiers: Auto-set. (line 174)
* program, definition of: Getting Started. (line 21)
* programming conventions, --non-decimal-data option: Nondecimal Data.
(line 35)
@@ -34827,7 +34910,7 @@ Index
* reading input files: Reading Files. (line 6)
* recipe for a programming language: History. (line 6)
* record separators: awk split records. (line 6)
-* record separators <1>: User-modified. (line 133)
+* record separators <1>: User-modified. (line 136)
* record separators, changing: awk split records. (line 85)
* record separators, regular expressions as: awk split records.
(line 124)
@@ -34869,7 +34952,7 @@ Index
* regular expressions, as record separators: awk split records.
(line 124)
* regular expressions, case sensitivity: Case-sensitivity. (line 6)
-* regular expressions, case sensitivity <1>: User-modified. (line 76)
+* regular expressions, case sensitivity <1>: User-modified. (line 79)
* regular expressions, computed: Computed Regexps. (line 6)
* regular expressions, constants, See regexp constants: Regexp Usage.
(line 57)
@@ -34919,7 +35002,7 @@ Index
* right shift: Bitwise Functions. (line 54)
* right shift, bitwise: Bitwise Functions. (line 32)
* Ritchie, Dennis: Basic Data Typing. (line 54)
-* RLENGTH variable: Auto-set. (line 282)
+* RLENGTH variable: Auto-set. (line 283)
* RLENGTH variable, match() function and: String Functions. (line 227)
* Robbins, Arnold: Command Line Field Separator.
(line 71)
@@ -34940,16 +35023,16 @@ Index
* round to nearest integer: Numeric Functions. (line 24)
* round() user-defined function: Round Function. (line 16)
* rounding numbers: Round Function. (line 6)
-* ROUNDMODE variable: User-modified. (line 128)
+* ROUNDMODE variable: User-modified. (line 131)
* RS variable: awk split records. (line 12)
-* RS variable <1>: User-modified. (line 133)
+* RS variable <1>: User-modified. (line 136)
* RS variable, multiline records and: Multiple Line. (line 17)
* rshift: Bitwise Functions. (line 54)
-* RSTART variable: Auto-set. (line 288)
+* RSTART variable: Auto-set. (line 289)
* RSTART variable, match() function and: String Functions. (line 227)
* RT variable: awk split records. (line 124)
* RT variable <1>: Multiple Line. (line 130)
-* RT variable <2>: Auto-set. (line 295)
+* RT variable <2>: Auto-set. (line 296)
* Rubin, Paul: History. (line 30)
* Rubin, Paul <1>: Contributors. (line 16)
* rule, definition of: Getting Started. (line 21)
@@ -34967,7 +35050,7 @@ Index
* scanning arrays: Scanning an Array. (line 6)
* scanning multidimensional arrays: Multiscanning. (line 11)
* Schorr, Andrew: Acknowledgments. (line 60)
-* Schorr, Andrew <1>: Auto-set. (line 327)
+* Schorr, Andrew <1>: Auto-set. (line 328)
* Schorr, Andrew <2>: Contributors. (line 134)
* Schreiber, Bert: Acknowledgments. (line 38)
* Schreiber, Rita: Acknowledgments. (line 38)
@@ -34994,17 +35077,17 @@ Index
(line 19)
* semicolon (;), separating statements in actions <2>: Statements.
(line 10)
-* separators, field: User-modified. (line 50)
-* separators, field <1>: User-modified. (line 113)
+* separators, field: User-modified. (line 53)
+* separators, field <1>: User-modified. (line 116)
* separators, field, FIELDWIDTHS variable and: User-modified. (line 37)
-* separators, field, FPAT variable and: User-modified. (line 43)
+* separators, field, FPAT variable and: User-modified. (line 46)
* separators, for records: awk split records. (line 6)
* separators, for records <1>: awk split records. (line 85)
-* separators, for records <2>: User-modified. (line 133)
+* separators, for records <2>: User-modified. (line 136)
* separators, for records, regular expressions as: awk split records.
(line 124)
* separators, for statements in actions: Action Overview. (line 19)
-* separators, subscript: User-modified. (line 146)
+* separators, subscript: User-modified. (line 149)
* set breakpoint: Breakpoint Control. (line 11)
* set debugger command: Viewing And Changing Data.
(line 58)
@@ -35053,7 +35136,7 @@ Index
* sidebar, Beware The Smoke and Mirrors!: Bitwise Functions. (line 126)
* sidebar, Changing FS Does Not Affect the Fields: Full Line Fields.
(line 14)
-* sidebar, Changing NR and FNR: Auto-set. (line 355)
+* sidebar, Changing NR and FNR: Auto-set. (line 356)
* sidebar, Controlling Output Buffering with system(): I/O Functions.
(line 164)
* sidebar, Escape Sequences for Metacharacters: Escape Sequences.
@@ -35138,7 +35221,7 @@ Index
* split.awk program: Split Program. (line 30)
* sprintf: OFMT. (line 15)
* sprintf <1>: String Functions. (line 384)
-* sprintf() function, OFMT variable and: User-modified. (line 113)
+* sprintf() function, OFMT variable and: User-modified. (line 116)
* sprintf() function, print/printf statements and: Round Function.
(line 6)
* sqrt: Numeric Functions. (line 93)
@@ -35184,7 +35267,7 @@ Index
* strings, converting <1>: Bitwise Functions. (line 108)
* strings, converting letter case: String Functions. (line 523)
* strings, converting, numbers to: User-modified. (line 30)
-* strings, converting, numbers to <1>: User-modified. (line 104)
+* strings, converting, numbers to <1>: User-modified. (line 107)
* strings, empty, See null strings: awk split records. (line 114)
* strings, extracting: String Extraction. (line 6)
* strings, for localization: Programmer i18n. (line 13)
@@ -35201,7 +35284,7 @@ Index
* sub <1>: String Functions. (line 409)
* sub() function, arguments of: String Functions. (line 463)
* sub() function, escape processing: Gory Details. (line 6)
-* subscript separators: User-modified. (line 146)
+* subscript separators: User-modified. (line 149)
* subscripts in arrays, multidimensional: Multidimensional. (line 10)
* subscripts in arrays, multidimensional, scanning: Multiscanning.
(line 11)
@@ -35209,16 +35292,16 @@ Index
(line 6)
* subscripts in arrays, uninitialized variables as: Uninitialized Subscripts.
(line 6)
-* SUBSEP variable: User-modified. (line 146)
+* SUBSEP variable: User-modified. (line 149)
* SUBSEP variable, and multidimensional arrays: Multidimensional.
(line 16)
* substitute in string: String Functions. (line 89)
* substr: String Functions. (line 482)
* substring: String Functions. (line 482)
* Sumner, Andrew: Other Versions. (line 68)
-* supplementary groups of gawk process: Auto-set. (line 251)
+* supplementary groups of gawk process: Auto-set. (line 252)
* switch statement: Switch Statement. (line 6)
-* SYMTAB array: Auto-set. (line 299)
+* SYMTAB array: Auto-set. (line 300)
* syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops.
(line 149)
* system: I/O Functions. (line 107)
@@ -35247,7 +35330,7 @@ Index
(line 6)
* text, printing: Print. (line 22)
* text, printing, unduplicated lines of: Uniq Program. (line 6)
-* TEXTDOMAIN variable: User-modified. (line 152)
+* TEXTDOMAIN variable: User-modified. (line 155)
* TEXTDOMAIN variable <1>: Programmer i18n. (line 8)
* TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n. (line 60)
* TEXTDOMAIN variable, portability and: I18N Portability. (line 20)
@@ -35400,10 +35483,10 @@ Index
* variables, uninitialized, as array subscripts: Uninitialized Subscripts.
(line 6)
* variables, user-defined: Variables. (line 6)
-* version of gawk: Auto-set. (line 221)
-* version of gawk extension API: Auto-set. (line 246)
-* version of GNU MP library: Auto-set. (line 229)
-* version of GNU MPFR library: Auto-set. (line 231)
+* version of gawk: Auto-set. (line 222)
+* version of gawk extension API: Auto-set. (line 247)
+* version of GNU MP library: Auto-set. (line 230)
+* version of GNU MPFR library: Auto-set. (line 232)
* vertical bar (|): Regexp Operators. (line 70)
* vertical bar (|), | operator (I/O): Getline/Pipe. (line 10)
* vertical bar (|), | operator (I/O) <1>: Precedence. (line 64)
@@ -35560,484 +35643,484 @@ Ref: Full Line Fields-Footnote-1228233
Ref: Full Line Fields-Footnote-2228279
Node: Field Splitting Summary228380
Node: Constant Size230454
-Node: Splitting By Content235032
-Ref: Splitting By Content-Footnote-1239003
-Node: Multiple Line239166
-Ref: Multiple Line-Footnote-1245048
-Node: Getline245227
-Node: Plain Getline247694
-Node: Getline/Variable250333
-Node: Getline/File251482
-Node: Getline/Variable/File252868
-Ref: Getline/Variable/File-Footnote-1254471
-Node: Getline/Pipe254559
-Node: Getline/Variable/Pipe257264
-Node: Getline/Coprocess258397
-Node: Getline/Variable/Coprocess259662
-Node: Getline Notes260402
-Node: Getline Summary263197
-Ref: table-getline-variants263619
-Node: Read Timeout264367
-Ref: Read Timeout-Footnote-1268273
-Node: Retrying Input268331
-Node: Command-line directories269530
-Node: Input Summary270436
-Node: Input Exercises273608
-Node: Printing274336
-Node: Print276170
-Node: Print Examples277627
-Node: Output Separators280407
-Node: OFMT282424
-Node: Printf283780
-Node: Basic Printf284565
-Node: Control Letters286139
-Node: Format Modifiers290127
-Node: Printf Examples296142
-Node: Redirection298628
-Node: Special FD305469
-Ref: Special FD-Footnote-1308637
-Node: Special Files308711
-Node: Other Inherited Files309328
-Node: Special Network310329
-Node: Special Caveats311189
-Node: Close Files And Pipes312138
-Ref: table-close-pipe-return-values319045
-Ref: Close Files And Pipes-Footnote-1319828
-Ref: Close Files And Pipes-Footnote-2319976
-Node: Nonfatal320128
-Node: Output Summary322453
-Node: Output Exercises323675
-Node: Expressions324354
-Node: Values325542
-Node: Constants326220
-Node: Scalar Constants326911
-Ref: Scalar Constants-Footnote-1327775
-Node: Nondecimal-numbers328025
-Node: Regexp Constants331026
-Node: Using Constant Regexps331552
-Node: Standard Regexp Constants332174
-Node: Strong Regexp Constants335362
-Node: Variables338320
-Node: Using Variables338977
-Node: Assignment Options340887
-Node: Conversion342760
-Node: Strings And Numbers343284
-Ref: Strings And Numbers-Footnote-1346347
-Node: Locale influences conversions346456
-Ref: table-locale-affects349214
-Node: All Operators349832
-Node: Arithmetic Ops350461
-Node: Concatenation352967
-Ref: Concatenation-Footnote-1355814
-Node: Assignment Ops355921
-Ref: table-assign-ops360912
-Node: Increment Ops362225
-Node: Truth Values and Conditions365685
-Node: Truth Values366759
-Node: Typing and Comparison367807
-Node: Variable Typing368627
-Ref: Variable Typing-Footnote-1375090
-Ref: Variable Typing-Footnote-2375162
-Node: Comparison Operators375239
-Ref: table-relational-ops375658
-Node: POSIX String Comparison379153
-Ref: POSIX String Comparison-Footnote-1380848
-Ref: POSIX String Comparison-Footnote-2380987
-Node: Boolean Ops381071
-Ref: Boolean Ops-Footnote-1385553
-Node: Conditional Exp385645
-Node: Function Calls387381
-Node: Precedence391258
-Node: Locales394917
-Node: Expressions Summary396549
-Node: Patterns and Actions399122
-Node: Pattern Overview400242
-Node: Regexp Patterns401919
-Node: Expression Patterns402461
-Node: Ranges406242
-Node: BEGIN/END409350
-Node: Using BEGIN/END410111
-Ref: Using BEGIN/END-Footnote-1412847
-Node: I/O And BEGIN/END412953
-Node: BEGINFILE/ENDFILE415267
-Node: Empty418174
-Node: Using Shell Variables418491
-Node: Action Overview420765
-Node: Statements423090
-Node: If Statement424938
-Node: While Statement426433
-Node: Do Statement428461
-Node: For Statement429609
-Node: Switch Statement432767
-Node: Break Statement435153
-Node: Continue Statement437245
-Node: Next Statement439072
-Node: Nextfile Statement441455
-Node: Exit Statement444107
-Node: Built-in Variables446510
-Node: User-modified447643
-Node: Auto-set455229
-Ref: Auto-set-Footnote-1469882
-Ref: Auto-set-Footnote-2470088
-Node: ARGC and ARGV470144
-Node: Pattern Action Summary474357
-Node: Arrays476787
-Node: Array Basics478116
-Node: Array Intro478960
-Ref: figure-array-elements480935
-Ref: Array Intro-Footnote-1483639
-Node: Reference to Elements483767
-Node: Assigning Elements486231
-Node: Array Example486722
-Node: Scanning an Array488481
-Node: Controlling Scanning491503
-Ref: Controlling Scanning-Footnote-1496902
-Node: Numeric Array Subscripts497218
-Node: Uninitialized Subscripts499402
-Node: Delete501021
-Ref: Delete-Footnote-1503773
-Node: Multidimensional503830
-Node: Multiscanning506925
-Node: Arrays of Arrays508516
-Node: Arrays Summary513283
-Node: Functions515376
-Node: Built-in516414
-Node: Calling Built-in517495
-Node: Numeric Functions519491
-Ref: Numeric Functions-Footnote-1524324
-Ref: Numeric Functions-Footnote-2524681
-Ref: Numeric Functions-Footnote-3524729
-Node: String Functions525001
-Ref: String Functions-Footnote-1548505
-Ref: String Functions-Footnote-2548633
-Ref: String Functions-Footnote-3548881
-Node: Gory Details548968
-Ref: table-sub-escapes550759
-Ref: table-sub-proposed552278
-Ref: table-posix-sub553641
-Ref: table-gensub-escapes555182
-Ref: Gory Details-Footnote-1556005
-Node: I/O Functions556159
-Ref: table-system-return-values562741
-Ref: I/O Functions-Footnote-1564721
-Ref: I/O Functions-Footnote-2564869
-Node: Time Functions564989
-Ref: Time Functions-Footnote-1575656
-Ref: Time Functions-Footnote-2575724
-Ref: Time Functions-Footnote-3575882
-Ref: Time Functions-Footnote-4575993
-Ref: Time Functions-Footnote-5576105
-Ref: Time Functions-Footnote-6576332
-Node: Bitwise Functions576598
-Ref: table-bitwise-ops577192
-Ref: Bitwise Functions-Footnote-1583225
-Ref: Bitwise Functions-Footnote-2583398
-Node: Type Functions583589
-Node: I18N Functions586264
-Node: User-defined587915
-Node: Definition Syntax588720
-Ref: Definition Syntax-Footnote-1594407
-Node: Function Example594478
-Ref: Function Example-Footnote-1597400
-Node: Function Caveats597422
-Node: Calling A Function597940
-Node: Variable Scope598898
-Node: Pass By Value/Reference601892
-Node: Return Statement605391
-Node: Dynamic Typing608370
-Node: Indirect Calls609300
-Ref: Indirect Calls-Footnote-1619551
-Node: Functions Summary619679
-Node: Library Functions622384
-Ref: Library Functions-Footnote-1625991
-Ref: Library Functions-Footnote-2626134
-Node: Library Names626305
-Ref: Library Names-Footnote-1629765
-Ref: Library Names-Footnote-2629988
-Node: General Functions630074
-Node: Strtonum Function631177
-Node: Assert Function634199
-Node: Round Function637525
-Node: Cliff Random Function639066
-Node: Ordinal Functions640082
-Ref: Ordinal Functions-Footnote-1643145
-Ref: Ordinal Functions-Footnote-2643397
-Node: Join Function643607
-Ref: Join Function-Footnote-1645377
-Node: Getlocaltime Function645577
-Node: Readfile Function649319
-Node: Shell Quoting651291
-Node: Data File Management652692
-Node: Filetrans Function653324
-Node: Rewind Function657420
-Node: File Checking659326
-Ref: File Checking-Footnote-1660660
-Node: Empty Files660861
-Node: Ignoring Assigns662840
-Node: Getopt Function664390
-Ref: Getopt Function-Footnote-1675859
-Node: Passwd Functions676059
-Ref: Passwd Functions-Footnote-1684898
-Node: Group Functions684986
-Ref: Group Functions-Footnote-1692884
-Node: Walking Arrays693091
-Node: Library Functions Summary696099
-Node: Library Exercises697505
-Node: Sample Programs697970
-Node: Running Examples698740
-Node: Clones699468
-Node: Cut Program700692
-Node: Egrep Program710621
-Ref: Egrep Program-Footnote-1718133
-Node: Id Program718243
-Node: Split Program721923
-Ref: Split Program-Footnote-1725382
-Node: Tee Program725511
-Node: Uniq Program728301
-Node: Wc Program735727
-Ref: Wc Program-Footnote-1739982
-Node: Miscellaneous Programs740076
-Node: Dupword Program741289
-Node: Alarm Program743319
-Node: Translate Program748174
-Ref: Translate Program-Footnote-1752739
-Node: Labels Program753009
-Ref: Labels Program-Footnote-1756360
-Node: Word Sorting756444
-Node: History Sorting760516
-Node: Extract Program762351
-Node: Simple Sed769880
-Node: Igawk Program772954
-Ref: Igawk Program-Footnote-1787285
-Ref: Igawk Program-Footnote-2787487
-Ref: Igawk Program-Footnote-3787609
-Node: Anagram Program787724
-Node: Signature Program790786
-Node: Programs Summary792033
-Node: Programs Exercises793247
-Ref: Programs Exercises-Footnote-1797376
-Node: Advanced Features797467
-Node: Nondecimal Data799457
-Node: Array Sorting801048
-Node: Controlling Array Traversal801748
-Ref: Controlling Array Traversal-Footnote-1810115
-Node: Array Sorting Functions810233
-Ref: Array Sorting Functions-Footnote-1815324
-Node: Two-way I/O815520
-Ref: Two-way I/O-Footnote-1822071
-Ref: Two-way I/O-Footnote-2822258
-Node: TCP/IP Networking822340
-Node: Profiling825458
-Ref: Profiling-Footnote-1834130
-Node: Advanced Features Summary834453
-Node: Internationalization836297
-Node: I18N and L10N837777
-Node: Explaining gettext838464
-Ref: Explaining gettext-Footnote-1844356
-Ref: Explaining gettext-Footnote-2844541
-Node: Programmer i18n844706
-Ref: Programmer i18n-Footnote-1849655
-Node: Translator i18n849704
-Node: String Extraction850498
-Ref: String Extraction-Footnote-1851630
-Node: Printf Ordering851716
-Ref: Printf Ordering-Footnote-1854502
-Node: I18N Portability854566
-Ref: I18N Portability-Footnote-1857022
-Node: I18N Example857085
-Ref: I18N Example-Footnote-1859891
-Node: Gawk I18N859964
-Node: I18N Summary860609
-Node: Debugger861950
-Node: Debugging862972
-Node: Debugging Concepts863413
-Node: Debugging Terms865222
-Node: Awk Debugging867797
-Node: Sample Debugging Session868703
-Node: Debugger Invocation869237
-Node: Finding The Bug870623
-Node: List of Debugger Commands877101
-Node: Breakpoint Control878434
-Node: Debugger Execution Control882128
-Node: Viewing And Changing Data885490
-Node: Execution Stack888864
-Node: Debugger Info890501
-Node: Miscellaneous Debugger Commands894572
-Node: Readline Support899660
-Node: Limitations900556
-Node: Debugging Summary902665
-Node: Arbitrary Precision Arithmetic903944
-Node: Computer Arithmetic905360
-Ref: table-numeric-ranges908951
-Ref: Computer Arithmetic-Footnote-1909673
-Node: Math Definitions909730
-Ref: table-ieee-formats913044
-Ref: Math Definitions-Footnote-1913647
-Node: MPFR features913752
-Node: FP Math Caution915469
-Ref: FP Math Caution-Footnote-1916541
-Node: Inexactness of computations916910
-Node: Inexact representation917870
-Node: Comparing FP Values919230
-Node: Errors accumulate920312
-Node: Getting Accuracy921745
-Node: Try To Round924455
-Node: Setting precision925354
-Ref: table-predefined-precision-strings926051
-Node: Setting the rounding mode927881
-Ref: table-gawk-rounding-modes928255
-Ref: Setting the rounding mode-Footnote-1931663
-Node: Arbitrary Precision Integers931842
-Ref: Arbitrary Precision Integers-Footnote-1936759
-Node: POSIX Floating Point Problems936908
-Ref: POSIX Floating Point Problems-Footnote-1940790
-Node: Floating point summary940828
-Node: Dynamic Extensions943018
-Node: Extension Intro944571
-Node: Plugin License945837
-Node: Extension Mechanism Outline946634
-Ref: figure-load-extension947073
-Ref: figure-register-new-function948638
-Ref: figure-call-new-function949730
-Node: Extension API Description951792
-Node: Extension API Functions Introduction953434
-Node: General Data Types958768
-Ref: General Data Types-Footnote-1965973
-Node: Memory Allocation Functions966272
-Ref: Memory Allocation Functions-Footnote-1969117
-Node: Constructor Functions969216
-Node: Registration Functions972215
-Node: Extension Functions972900
-Node: Exit Callback Functions978113
-Node: Extension Version String979363
-Node: Input Parsers980026
-Node: Output Wrappers989908
-Node: Two-way processors994420
-Node: Printing Messages996685
-Ref: Printing Messages-Footnote-1997856
-Node: Updating ERRNO998009
-Node: Requesting Values998748
-Ref: table-value-types-returned999485
-Node: Accessing Parameters1000421
-Node: Symbol Table Access1001656
-Node: Symbol table by name1002168
-Node: Symbol table by cookie1003957
-Ref: Symbol table by cookie-Footnote-11008142
-Node: Cached values1008206
-Ref: Cached values-Footnote-11011742
-Node: Array Manipulation1011833
-Ref: Array Manipulation-Footnote-11012924
-Node: Array Data Types1012961
-Ref: Array Data Types-Footnote-11015619
-Node: Array Functions1015711
-Node: Flattening Arrays1020110
-Node: Creating Arrays1027051
-Node: Redirection API1031820
-Node: Extension API Variables1034662
-Node: Extension Versioning1035295
-Ref: gawk-api-version1035732
-Node: Extension API Informational Variables1037460
-Node: Extension API Boilerplate1038524
-Node: Changes from API V11042386
-Node: Finding Extensions1043046
-Node: Extension Example1043605
-Node: Internal File Description1044403
-Node: Internal File Ops1048483
-Ref: Internal File Ops-Footnote-11059883
-Node: Using Internal File Ops1060023
-Ref: Using Internal File Ops-Footnote-11062406
-Node: Extension Samples1062680
-Node: Extension Sample File Functions1064209
-Node: Extension Sample Fnmatch1071858
-Node: Extension Sample Fork1073345
-Node: Extension Sample Inplace1074563
-Node: Extension Sample Ord1077773
-Node: Extension Sample Readdir1078609
-Ref: table-readdir-file-types1079498
-Node: Extension Sample Revout1080303
-Node: Extension Sample Rev2way1080892
-Node: Extension Sample Read write array1081632
-Node: Extension Sample Readfile1083574
-Node: Extension Sample Time1084669
-Node: Extension Sample API Tests1086017
-Node: gawkextlib1086509
-Node: Extension summary1088956
-Node: Extension Exercises1092658
-Node: Language History1094156
-Node: V7/SVR3.11095812
-Node: SVR41097964
-Node: POSIX1099398
-Node: BTL1100777
-Node: POSIX/GNU1101506
-Node: Feature History1107398
-Node: Common Extensions1121768
-Node: Ranges and Locales1123051
-Ref: Ranges and Locales-Footnote-11127667
-Ref: Ranges and Locales-Footnote-21127694
-Ref: Ranges and Locales-Footnote-31127929
-Node: Contributors1128150
-Node: History summary1133710
-Node: Installation1135090
-Node: Gawk Distribution1136034
-Node: Getting1136518
-Node: Extracting1137479
-Node: Distribution contents1139117
-Node: Unix Installation1145459
-Node: Quick Installation1146141
-Node: Shell Startup Files1148555
-Node: Additional Configuration Options1149644
-Node: Configuration Philosophy1151449
-Node: Non-Unix Installation1153818
-Node: PC Installation1154278
-Node: PC Binary Installation1155116
-Node: PC Compiling1155551
-Node: PC Using1156668
-Node: Cygwin1159713
-Node: MSYS1160483
-Node: VMS Installation1160984
-Node: VMS Compilation1161775
-Ref: VMS Compilation-Footnote-11163004
-Node: VMS Dynamic Extensions1163062
-Node: VMS Installation Details1164747
-Node: VMS Running1167000
-Node: VMS GNV1171279
-Node: VMS Old Gawk1172014
-Node: Bugs1172485
-Node: Bug address1173148
-Node: Usenet1175545
-Node: Maintainers1176322
-Node: Other Versions1177698
-Node: Installation summary1184282
-Node: Notes1185317
-Node: Compatibility Mode1186182
-Node: Additions1186964
-Node: Accessing The Source1187889
-Node: Adding Code1189324
-Node: New Ports1195542
-Node: Derived Files1200030
-Ref: Derived Files-Footnote-11205515
-Ref: Derived Files-Footnote-21205550
-Ref: Derived Files-Footnote-31206148
-Node: Future Extensions1206262
-Node: Implementation Limitations1206920
-Node: Extension Design1208103
-Node: Old Extension Problems1209257
-Ref: Old Extension Problems-Footnote-11210775
-Node: Extension New Mechanism Goals1210832
-Ref: Extension New Mechanism Goals-Footnote-11214196
-Node: Extension Other Design Decisions1214385
-Node: Extension Future Growth1216498
-Node: Old Extension Mechanism1217334
-Node: Notes summary1219097
-Node: Basic Concepts1220279
-Node: Basic High Level1220960
-Ref: figure-general-flow1221242
-Ref: figure-process-flow1221927
-Ref: Basic High Level-Footnote-11225228
-Node: Basic Data Typing1225413
-Node: Glossary1228741
-Node: Copying1260688
-Node: GNU Free Documentation License1298227
-Node: Index1323345
+Node: Splitting By Content235768
+Ref: Splitting By Content-Footnote-1239908
+Node: Multiple Line240071
+Ref: Multiple Line-Footnote-1245953
+Node: Getline246132
+Node: Plain Getline248599
+Node: Getline/Variable251238
+Node: Getline/File252387
+Node: Getline/Variable/File253773
+Ref: Getline/Variable/File-Footnote-1255376
+Node: Getline/Pipe255464
+Node: Getline/Variable/Pipe258169
+Node: Getline/Coprocess259302
+Node: Getline/Variable/Coprocess260567
+Node: Getline Notes261307
+Node: Getline Summary264102
+Ref: table-getline-variants264524
+Node: Read Timeout265272
+Ref: Read Timeout-Footnote-1269178
+Node: Retrying Input269236
+Node: Command-line directories270435
+Node: Input Summary271341
+Node: Input Exercises274513
+Node: Printing275241
+Node: Print277075
+Node: Print Examples278532
+Node: Output Separators281312
+Node: OFMT283329
+Node: Printf284685
+Node: Basic Printf285470
+Node: Control Letters287044
+Node: Format Modifiers291032
+Node: Printf Examples297047
+Node: Redirection299533
+Node: Special FD306374
+Ref: Special FD-Footnote-1309542
+Node: Special Files309616
+Node: Other Inherited Files310233
+Node: Special Network311234
+Node: Special Caveats312094
+Node: Close Files And Pipes313043
+Ref: table-close-pipe-return-values319950
+Ref: Close Files And Pipes-Footnote-1320733
+Ref: Close Files And Pipes-Footnote-2320881
+Node: Nonfatal321033
+Node: Output Summary323358
+Node: Output Exercises324580
+Node: Expressions325259
+Node: Values326447
+Node: Constants327125
+Node: Scalar Constants327816
+Ref: Scalar Constants-Footnote-1328680
+Node: Nondecimal-numbers328930
+Node: Regexp Constants331931
+Node: Using Constant Regexps332457
+Node: Standard Regexp Constants333079
+Node: Strong Regexp Constants336267
+Node: Variables339225
+Node: Using Variables339882
+Node: Assignment Options341792
+Node: Conversion343665
+Node: Strings And Numbers344189
+Ref: Strings And Numbers-Footnote-1347252
+Node: Locale influences conversions347361
+Ref: table-locale-affects350119
+Node: All Operators350737
+Node: Arithmetic Ops351366
+Node: Concatenation353872
+Ref: Concatenation-Footnote-1356719
+Node: Assignment Ops356826
+Ref: table-assign-ops361817
+Node: Increment Ops363130
+Node: Truth Values and Conditions366590
+Node: Truth Values367664
+Node: Typing and Comparison368712
+Node: Variable Typing369532
+Ref: Variable Typing-Footnote-1375995
+Ref: Variable Typing-Footnote-2376067
+Node: Comparison Operators376144
+Ref: table-relational-ops376563
+Node: POSIX String Comparison380058
+Ref: POSIX String Comparison-Footnote-1381753
+Ref: POSIX String Comparison-Footnote-2381892
+Node: Boolean Ops381976
+Ref: Boolean Ops-Footnote-1386458
+Node: Conditional Exp386550
+Node: Function Calls388286
+Node: Precedence392163
+Node: Locales395822
+Node: Expressions Summary397454
+Node: Patterns and Actions400027
+Node: Pattern Overview401147
+Node: Regexp Patterns402824
+Node: Expression Patterns403366
+Node: Ranges407147
+Node: BEGIN/END410255
+Node: Using BEGIN/END411016
+Ref: Using BEGIN/END-Footnote-1413752
+Node: I/O And BEGIN/END413858
+Node: BEGINFILE/ENDFILE416172
+Node: Empty419079
+Node: Using Shell Variables419396
+Node: Action Overview421670
+Node: Statements423995
+Node: If Statement425843
+Node: While Statement427338
+Node: Do Statement429366
+Node: For Statement430514
+Node: Switch Statement433672
+Node: Break Statement436058
+Node: Continue Statement438150
+Node: Next Statement439977
+Node: Nextfile Statement442360
+Node: Exit Statement445012
+Node: Built-in Variables447415
+Node: User-modified448548
+Node: Auto-set456315
+Ref: Auto-set-Footnote-1471043
+Ref: Auto-set-Footnote-2471249
+Node: ARGC and ARGV471305
+Node: Pattern Action Summary475518
+Node: Arrays477948
+Node: Array Basics479277
+Node: Array Intro480121
+Ref: figure-array-elements482096
+Ref: Array Intro-Footnote-1484800
+Node: Reference to Elements484928
+Node: Assigning Elements487392
+Node: Array Example487883
+Node: Scanning an Array489642
+Node: Controlling Scanning492664
+Ref: Controlling Scanning-Footnote-1498063
+Node: Numeric Array Subscripts498379
+Node: Uninitialized Subscripts500563
+Node: Delete502182
+Ref: Delete-Footnote-1504934
+Node: Multidimensional504991
+Node: Multiscanning508086
+Node: Arrays of Arrays509677
+Node: Arrays Summary514444
+Node: Functions516537
+Node: Built-in517575
+Node: Calling Built-in518656
+Node: Numeric Functions520652
+Ref: Numeric Functions-Footnote-1525485
+Ref: Numeric Functions-Footnote-2525842
+Ref: Numeric Functions-Footnote-3525890
+Node: String Functions526162
+Ref: String Functions-Footnote-1549666
+Ref: String Functions-Footnote-2549794
+Ref: String Functions-Footnote-3550042
+Node: Gory Details550129
+Ref: table-sub-escapes551920
+Ref: table-sub-proposed553439
+Ref: table-posix-sub554802
+Ref: table-gensub-escapes556343
+Ref: Gory Details-Footnote-1557166
+Node: I/O Functions557320
+Ref: table-system-return-values563902
+Ref: I/O Functions-Footnote-1565882
+Ref: I/O Functions-Footnote-2566030
+Node: Time Functions566150
+Ref: Time Functions-Footnote-1576817
+Ref: Time Functions-Footnote-2576885
+Ref: Time Functions-Footnote-3577043
+Ref: Time Functions-Footnote-4577154
+Ref: Time Functions-Footnote-5577266
+Ref: Time Functions-Footnote-6577493
+Node: Bitwise Functions577759
+Ref: table-bitwise-ops578353
+Ref: Bitwise Functions-Footnote-1584386
+Ref: Bitwise Functions-Footnote-2584559
+Node: Type Functions584750
+Node: I18N Functions587425
+Node: User-defined589076
+Node: Definition Syntax589881
+Ref: Definition Syntax-Footnote-1595568
+Node: Function Example595639
+Ref: Function Example-Footnote-1598561
+Node: Function Caveats598583
+Node: Calling A Function599101
+Node: Variable Scope600059
+Node: Pass By Value/Reference603053
+Node: Return Statement606552
+Node: Dynamic Typing609531
+Node: Indirect Calls610461
+Ref: Indirect Calls-Footnote-1620712
+Node: Functions Summary620840
+Node: Library Functions623545
+Ref: Library Functions-Footnote-1627152
+Ref: Library Functions-Footnote-2627295
+Node: Library Names627466
+Ref: Library Names-Footnote-1630926
+Ref: Library Names-Footnote-2631149
+Node: General Functions631235
+Node: Strtonum Function632338
+Node: Assert Function635360
+Node: Round Function638686
+Node: Cliff Random Function640227
+Node: Ordinal Functions641243
+Ref: Ordinal Functions-Footnote-1644306
+Ref: Ordinal Functions-Footnote-2644558
+Node: Join Function644768
+Ref: Join Function-Footnote-1646538
+Node: Getlocaltime Function646738
+Node: Readfile Function650480
+Node: Shell Quoting652452
+Node: Data File Management653853
+Node: Filetrans Function654485
+Node: Rewind Function658581
+Node: File Checking660487
+Ref: File Checking-Footnote-1661821
+Node: Empty Files662022
+Node: Ignoring Assigns664001
+Node: Getopt Function665551
+Ref: Getopt Function-Footnote-1677020
+Node: Passwd Functions677220
+Ref: Passwd Functions-Footnote-1686059
+Node: Group Functions686147
+Ref: Group Functions-Footnote-1694045
+Node: Walking Arrays694252
+Node: Library Functions Summary697260
+Node: Library Exercises698666
+Node: Sample Programs699131
+Node: Running Examples699901
+Node: Clones700629
+Node: Cut Program701853
+Node: Egrep Program711782
+Ref: Egrep Program-Footnote-1719294
+Node: Id Program719404
+Node: Split Program723084
+Ref: Split Program-Footnote-1726543
+Node: Tee Program726672
+Node: Uniq Program729462
+Node: Wc Program736888
+Ref: Wc Program-Footnote-1741143
+Node: Miscellaneous Programs741237
+Node: Dupword Program742450
+Node: Alarm Program744480
+Node: Translate Program749335
+Ref: Translate Program-Footnote-1753900
+Node: Labels Program754170
+Ref: Labels Program-Footnote-1757521
+Node: Word Sorting757605
+Node: History Sorting761677
+Node: Extract Program763512
+Node: Simple Sed771041
+Node: Igawk Program774115
+Ref: Igawk Program-Footnote-1788446
+Ref: Igawk Program-Footnote-2788648
+Ref: Igawk Program-Footnote-3788770
+Node: Anagram Program788885
+Node: Signature Program791947
+Node: Programs Summary793194
+Node: Programs Exercises794408
+Ref: Programs Exercises-Footnote-1798537
+Node: Advanced Features798628
+Node: Nondecimal Data800618
+Node: Array Sorting802209
+Node: Controlling Array Traversal802909
+Ref: Controlling Array Traversal-Footnote-1811276
+Node: Array Sorting Functions811394
+Ref: Array Sorting Functions-Footnote-1816485
+Node: Two-way I/O816681
+Ref: Two-way I/O-Footnote-1823232
+Ref: Two-way I/O-Footnote-2823419
+Node: TCP/IP Networking823501
+Node: Profiling826619
+Ref: Profiling-Footnote-1835291
+Node: Advanced Features Summary835614
+Node: Internationalization837458
+Node: I18N and L10N838938
+Node: Explaining gettext839625
+Ref: Explaining gettext-Footnote-1845517
+Ref: Explaining gettext-Footnote-2845702
+Node: Programmer i18n845867
+Ref: Programmer i18n-Footnote-1850816
+Node: Translator i18n850865
+Node: String Extraction851659
+Ref: String Extraction-Footnote-1852791
+Node: Printf Ordering852877
+Ref: Printf Ordering-Footnote-1855663
+Node: I18N Portability855727
+Ref: I18N Portability-Footnote-1858183
+Node: I18N Example858246
+Ref: I18N Example-Footnote-1861052
+Node: Gawk I18N861125
+Node: I18N Summary861770
+Node: Debugger863111
+Node: Debugging864133
+Node: Debugging Concepts864574
+Node: Debugging Terms866383
+Node: Awk Debugging868958
+Node: Sample Debugging Session869864
+Node: Debugger Invocation870398
+Node: Finding The Bug871784
+Node: List of Debugger Commands878262
+Node: Breakpoint Control879595
+Node: Debugger Execution Control883289
+Node: Viewing And Changing Data886651
+Node: Execution Stack890025
+Node: Debugger Info891662
+Node: Miscellaneous Debugger Commands895733
+Node: Readline Support900821
+Node: Limitations901717
+Node: Debugging Summary903826
+Node: Arbitrary Precision Arithmetic905105
+Node: Computer Arithmetic906521
+Ref: table-numeric-ranges910112
+Ref: Computer Arithmetic-Footnote-1910834
+Node: Math Definitions910891
+Ref: table-ieee-formats914205
+Ref: Math Definitions-Footnote-1914808
+Node: MPFR features914913
+Node: FP Math Caution916630
+Ref: FP Math Caution-Footnote-1917702
+Node: Inexactness of computations918071
+Node: Inexact representation919031
+Node: Comparing FP Values920391
+Node: Errors accumulate921473
+Node: Getting Accuracy922906
+Node: Try To Round925616
+Node: Setting precision926515
+Ref: table-predefined-precision-strings927212
+Node: Setting the rounding mode929042
+Ref: table-gawk-rounding-modes929416
+Ref: Setting the rounding mode-Footnote-1932824
+Node: Arbitrary Precision Integers933003
+Ref: Arbitrary Precision Integers-Footnote-1937920
+Node: POSIX Floating Point Problems938069
+Ref: POSIX Floating Point Problems-Footnote-1941951
+Node: Floating point summary941989
+Node: Dynamic Extensions944179
+Node: Extension Intro945732
+Node: Plugin License946998
+Node: Extension Mechanism Outline947795
+Ref: figure-load-extension948234
+Ref: figure-register-new-function949799
+Ref: figure-call-new-function950891
+Node: Extension API Description952953
+Node: Extension API Functions Introduction954595
+Node: General Data Types959929
+Ref: General Data Types-Footnote-1967134
+Node: Memory Allocation Functions967433
+Ref: Memory Allocation Functions-Footnote-1970278
+Node: Constructor Functions970377
+Node: Registration Functions973376
+Node: Extension Functions974061
+Node: Exit Callback Functions979274
+Node: Extension Version String980524
+Node: Input Parsers981187
+Node: Output Wrappers993921
+Node: Two-way processors998433
+Node: Printing Messages1000698
+Ref: Printing Messages-Footnote-11001869
+Node: Updating ERRNO1002022
+Node: Requesting Values1002761
+Ref: table-value-types-returned1003498
+Node: Accessing Parameters1004434
+Node: Symbol Table Access1005669
+Node: Symbol table by name1006181
+Node: Symbol table by cookie1007970
+Ref: Symbol table by cookie-Footnote-11012155
+Node: Cached values1012219
+Ref: Cached values-Footnote-11015755
+Node: Array Manipulation1015846
+Ref: Array Manipulation-Footnote-11016937
+Node: Array Data Types1016974
+Ref: Array Data Types-Footnote-11019632
+Node: Array Functions1019724
+Node: Flattening Arrays1024123
+Node: Creating Arrays1031064
+Node: Redirection API1035833
+Node: Extension API Variables1038675
+Node: Extension Versioning1039308
+Ref: gawk-api-version1039745
+Node: Extension API Informational Variables1041473
+Node: Extension API Boilerplate1042537
+Node: Changes from API V11046399
+Node: Finding Extensions1047059
+Node: Extension Example1047618
+Node: Internal File Description1048416
+Node: Internal File Ops1052496
+Ref: Internal File Ops-Footnote-11063896
+Node: Using Internal File Ops1064036
+Ref: Using Internal File Ops-Footnote-11066419
+Node: Extension Samples1066693
+Node: Extension Sample File Functions1068222
+Node: Extension Sample Fnmatch1075871
+Node: Extension Sample Fork1077358
+Node: Extension Sample Inplace1078576
+Node: Extension Sample Ord1081786
+Node: Extension Sample Readdir1082622
+Ref: table-readdir-file-types1083511
+Node: Extension Sample Revout1084316
+Node: Extension Sample Rev2way1084905
+Node: Extension Sample Read write array1085645
+Node: Extension Sample Readfile1087587
+Node: Extension Sample Time1088682
+Node: Extension Sample API Tests1090030
+Node: gawkextlib1090522
+Node: Extension summary1092969
+Node: Extension Exercises1096671
+Node: Language History1098169
+Node: V7/SVR3.11099825
+Node: SVR41101977
+Node: POSIX1103411
+Node: BTL1104790
+Node: POSIX/GNU1105519
+Node: Feature History1111411
+Node: Common Extensions1125781
+Node: Ranges and Locales1127064
+Ref: Ranges and Locales-Footnote-11131680
+Ref: Ranges and Locales-Footnote-21131707
+Ref: Ranges and Locales-Footnote-31131942
+Node: Contributors1132163
+Node: History summary1137723
+Node: Installation1139103
+Node: Gawk Distribution1140047
+Node: Getting1140531
+Node: Extracting1141492
+Node: Distribution contents1143130
+Node: Unix Installation1149472
+Node: Quick Installation1150154
+Node: Shell Startup Files1152568
+Node: Additional Configuration Options1153657
+Node: Configuration Philosophy1155462
+Node: Non-Unix Installation1157831
+Node: PC Installation1158291
+Node: PC Binary Installation1159129
+Node: PC Compiling1159564
+Node: PC Using1160681
+Node: Cygwin1163726
+Node: MSYS1164496
+Node: VMS Installation1164997
+Node: VMS Compilation1165788
+Ref: VMS Compilation-Footnote-11167017
+Node: VMS Dynamic Extensions1167075
+Node: VMS Installation Details1168760
+Node: VMS Running1171013
+Node: VMS GNV1175292
+Node: VMS Old Gawk1176027
+Node: Bugs1176498
+Node: Bug address1177161
+Node: Usenet1179558
+Node: Maintainers1180335
+Node: Other Versions1181711
+Node: Installation summary1188295
+Node: Notes1189330
+Node: Compatibility Mode1190195
+Node: Additions1190977
+Node: Accessing The Source1191902
+Node: Adding Code1193337
+Node: New Ports1199555
+Node: Derived Files1204043
+Ref: Derived Files-Footnote-11209528
+Ref: Derived Files-Footnote-21209563
+Ref: Derived Files-Footnote-31210161
+Node: Future Extensions1210275
+Node: Implementation Limitations1210933
+Node: Extension Design1212116
+Node: Old Extension Problems1213270
+Ref: Old Extension Problems-Footnote-11214788
+Node: Extension New Mechanism Goals1214845
+Ref: Extension New Mechanism Goals-Footnote-11218209
+Node: Extension Other Design Decisions1218398
+Node: Extension Future Growth1220511
+Node: Old Extension Mechanism1221347
+Node: Notes summary1223110
+Node: Basic Concepts1224292
+Node: Basic High Level1224973
+Ref: figure-general-flow1225255
+Ref: figure-process-flow1225940
+Ref: Basic High Level-Footnote-11229241
+Node: Basic Data Typing1229426
+Node: Glossary1232754
+Node: Copying1264701
+Node: GNU Free Documentation License1302240
+Node: Index1327358
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 658ac17..f2d1751 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -7761,6 +7761,9 @@ variable @code{FIELDWIDTHS}. Each number specifies the
width of the field,
@emph{including} columns between fields. If you want to ignore the columns
between fields, you can specify the width as a separate field that is
subsequently ignored.
+Or, starting in @value{PVERSION} 4.2, each field width may optionally be
+preceded by a colon-separated value specifying the number of characters to skip
+before the field starts.
It is a fatal error to supply a field width that has a negative value.
The following data is the output of the Unix @command{w} utility. It is useful
to illustrate the use of @code{FIELDWIDTHS}:
@@ -7820,6 +7823,24 @@ brent ttyp0 286
dave ttyq4 1296000
@end example
+Starting in @value{PVERSION} 4.2, this program could be rewritten to
+specify @code{FIELDWIDTHS} like so:
address@hidden
+BEGIN @{ FIELDWIDTHS = "8 1:5 4:7 6 1:6 1:6 2:33" @}
address@hidden example
+This strips away some of the white space separating the fields. With such
+a change, the program would produce the following results:
+
address@hidden
+hzang ttyV3 50
+eklye ttyV5 0
+dportein ttyV6 107
+gierd ttyD3 1
+dave ttyD4 0
+brent ttyp0 286
+dave ttyq4 1296000
address@hidden example
+
Another (possibly more practical) example of fixed-width input data
is the input from a deck of balloting cards. In some parts of
the United States, voters mark their choices by punching holes in computer
@@ -7845,8 +7866,10 @@ if (PROCINFO["FS"] == "FS")
@var{regular field splitting} @dots{}
else if (PROCINFO["FS"] == "FIELDWIDTHS")
@var{fixed-width field splitting} @dots{}
-else
+else if (PROCINFO["FS"] == "FPAT")
@var{content-based field splitting} @dots{} @ii{(see next @value{SECTION})}
+else
+ @var{API input parser field splitting} @dots{} @ii{(@pxref{Input Parsers})}
@end example
This information is useful when writing a function
@@ -7986,7 +8009,9 @@ To recap, @command{gawk} provides three independent
methods
to split input records into fields.
The mechanism used is based on which of the three
address@hidden, @code{FIELDWIDTHS}, or @code{FPAT}---was
-last assigned to.
+last assigned to. In addition, an API input parser may choose to
+override the record parsing mechanism; please refer to @pxref{Input Parsers}
+for further information about this feature.
@node Multiple Line
@section Multiple-Line Records
@@ -14972,6 +14997,9 @@ Its default value is @code{"%.6g"}.
@item FIELDWIDTHS #
A space-separated list of columns that tells @command{gawk}
how to split input with fixed columnar boundaries.
+Starting in @value{PVERSION} 4.2, each field width may optionally be
+preceded by a colon-separated value specifying the number of characters to skip
+before the field starts.
Assigning a value to @code{FIELDWIDTHS}
overrides the use of @code{FS} and @code{FPAT} for field splitting.
@xref{Constant Size} for more information.
@@ -15366,7 +15394,8 @@ The value of the @code{geteuid()} system call.
This is
@code{"FS"} if field splitting with @code{FS} is in effect,
@code{"FIELDWIDTHS"} if field splitting with @code{FIELDWIDTHS} is in effect,
-or @code{"FPAT"} if field matching with @code{FPAT} is in effect.
address@hidden"FPAT"} if field matching with @code{FPAT} is in effect,
+or @code{"API"} if field splitting is controlled by an API input parser.
@item PROCINFO["gid"]
@cindex group ID of @command{gawk} user
@@ -33165,7 +33194,8 @@ typedef struct awk_input @{
#define INVALID_HANDLE (-1)
void *opaque; /* private data for input parsers */
int (*get_record)(char **out, struct awk_input *iobuf,
- int *errcode, char **rt_start, size_t *rt_len);
+ int *errcode, char **rt_start, size_t *rt_len,
+ const awk_fieldwidth_info_t **field_width);
ssize_t (*read_func)();
void (*close_func)(struct awk_input *iobuf);
struct stat sbuf; /* stat buf */
@@ -33217,7 +33247,8 @@ is not required to use this pointer.
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ struct@ awk_input *iobuf,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int *errcode,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ char **rt_start,
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len);
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len,
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_fieldwidth_info_t
**field_width);
This function pointer should point to a function that creates the input
records. Said function is the core of the input parser. Its behavior
is described in the text following this list.
@@ -33269,6 +33300,21 @@ If the concept of a ``record terminator'' makes sense,
then
data. Otherwise, @code{*rt_len} should be set to zero.
@command{gawk} makes its own copy of this data, so the
extension must manage this storage.
+
address@hidden const awk_fieldwidth_info_t **field_width
+If @code{field_width} is not @code{NULL}, then @code{*field_width} will be
initialized
+to @code{NULL}, and the function may set it to point to a structure
+supplying field width information to override the default
+field parsing mechanism. Note that this structure will not
+be copied by @command{gawk}; it must persist at least until the next call
+to @code{get_record} or @code{close_func}. Note also that @code{field_width}
will
+be @code{NULL} when @code{getline} is assigning the results to a variable, thus
+field parsing is not needed. If the parser does set @code{*field_width},
+then @command{gawk} will use this layout to parse the input record,
+and the @code{PROCINFO["FS"]} value will be @code{"API"} while this record
+is active in @code{$0}.
+The @code{awk_fieldwidth_info_t} data structure
+is described below.
@end table
The return value is the length of the buffer pointed to by
@@ -33327,6 +33373,50 @@ Register the input parser pointed to by
@code{input_parser} with
@command{gawk}.
@end table
+If you would like to override the default field parsing mechanism for a given
+record, then you must populate the @code{awk_fieldwidth_info_t} structure,
+which looks like this:
+
address@hidden
+typedef struct @{
+ awk_bool_t use_chars; /* false ==> use bytes */
+ size_t nf; /* number of fields in record (NF) */
+ struct awk_field_info @{
+ size_t skip; /* amount to skip before field starts */
+ size_t len; /* length of field */
+ @} fields[1]; /* actual dimension should be nf */
address@hidden awk_fieldwidth_info_t;
address@hidden example
+
+The fields are:
+
address@hidden @code
address@hidden awk_bool_t use_chars;
+Set this to @code{awk_true} if the field lengths are specified in terms
+of potentially multi-byte characters, and set it to @code{awk_false} if
+the lengths are in terms of bytes.
+Performance will be better if the values are supplied in
+terms of bytes.
+
address@hidden size_t nf;
+Set this to the number of fields in the input record, i.e. @code{NF}.
+
address@hidden struct awk_field_info fields[nf];
+This is a variable-length array whose actual dimension should be @code{nf}.
+For each field, the @code{skip} element should be set to the number
+of characters or bytes, as controlled by the @code{use_chars} flag,
+to skip before the start of this field. And the @code{len} element provides
+the length of the field. The values in @code{fields[0]} provide the information
+for the @code{$1} field, and so on through the @code{fields[nf-1]} element
containing the information for @code{$NF}.
address@hidden table
+
+A convenience macro @code{awk_fieldwidth_info_size(NF)} is provided to
+calculate the appropriate size of a variable-length
address@hidden structure containing @code{NF} fields. This can
+be used as an argument to @code{malloc} or in a union to allocate space
+statically. Please refer to the sample extension @code{readdir_test} for an
+example.
+
@node Output Wrappers
@subsubsection Customized Output Wrappers
@cindex customized output wrapper
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index d8e9654..78a2823 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -7361,6 +7361,9 @@ variable @code{FIELDWIDTHS}. Each number specifies the
width of the field,
@emph{including} columns between fields. If you want to ignore the columns
between fields, you can specify the width as a separate field that is
subsequently ignored.
+Or, starting in @value{PVERSION} 4.2, each field width may optionally be
+preceded by a colon-separated value specifying the number of characters to skip
+before the field starts.
It is a fatal error to supply a field width that has a negative value.
The following data is the output of the Unix @command{w} utility. It is useful
to illustrate the use of @code{FIELDWIDTHS}:
@@ -7420,6 +7423,24 @@ brent ttyp0 286
dave ttyq4 1296000
@end example
+Starting in @value{PVERSION} 4.2, this program could be rewritten to
+specify @code{FIELDWIDTHS} like so:
address@hidden
+BEGIN @{ FIELDWIDTHS = "8 1:5 4:7 6 1:6 1:6 2:33" @}
address@hidden example
+This strips away some of the white space separating the fields. With such
+a change, the program would produce the following results:
+
address@hidden
+hzang ttyV3 50
+eklye ttyV5 0
+dportein ttyV6 107
+gierd ttyD3 1
+dave ttyD4 0
+brent ttyp0 286
+dave ttyq4 1296000
address@hidden example
+
Another (possibly more practical) example of fixed-width input data
is the input from a deck of balloting cards. In some parts of
the United States, voters mark their choices by punching holes in computer
@@ -7445,8 +7466,10 @@ if (PROCINFO["FS"] == "FS")
@var{regular field splitting} @dots{}
else if (PROCINFO["FS"] == "FIELDWIDTHS")
@var{fixed-width field splitting} @dots{}
-else
+else if (PROCINFO["FS"] == "FPAT")
@var{content-based field splitting} @dots{} @ii{(see next @value{SECTION})}
+else
+ @var{API input parser field splitting} @dots{} @ii{(@pxref{Input Parsers})}
@end example
This information is useful when writing a function
@@ -7586,7 +7609,9 @@ To recap, @command{gawk} provides three independent
methods
to split input records into fields.
The mechanism used is based on which of the three
address@hidden, @code{FIELDWIDTHS}, or @code{FPAT}---was
-last assigned to.
+last assigned to. In addition, an API input parser may choose to
+override the record parsing mechanism; please refer to @pxref{Input Parsers}
+for further information about this feature.
@node Multiple Line
@section Multiple-Line Records
@@ -14291,6 +14316,9 @@ Its default value is @code{"%.6g"}.
@item FIELDWIDTHS #
A space-separated list of columns that tells @command{gawk}
how to split input with fixed columnar boundaries.
+Starting in @value{PVERSION} 4.2, each field width may optionally be
+preceded by a colon-separated value specifying the number of characters to skip
+before the field starts.
Assigning a value to @code{FIELDWIDTHS}
overrides the use of @code{FS} and @code{FPAT} for field splitting.
@xref{Constant Size} for more information.
@@ -14685,7 +14713,8 @@ The value of the @code{geteuid()} system call.
This is
@code{"FS"} if field splitting with @code{FS} is in effect,
@code{"FIELDWIDTHS"} if field splitting with @code{FIELDWIDTHS} is in effect,
-or @code{"FPAT"} if field matching with @code{FPAT} is in effect.
address@hidden"FPAT"} if field matching with @code{FPAT} is in effect,
+or @code{"API"} if field splitting is controlled by an API input parser.
@item PROCINFO["gid"]
@cindex group ID of @command{gawk} user
@@ -32179,7 +32208,8 @@ typedef struct awk_input @{
#define INVALID_HANDLE (-1)
void *opaque; /* private data for input parsers */
int (*get_record)(char **out, struct awk_input *iobuf,
- int *errcode, char **rt_start, size_t *rt_len);
+ int *errcode, char **rt_start, size_t *rt_len,
+ const awk_fieldwidth_info_t **field_width);
ssize_t (*read_func)();
void (*close_func)(struct awk_input *iobuf);
struct stat sbuf; /* stat buf */
@@ -32231,7 +32261,8 @@ is not required to use this pointer.
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ struct@ awk_input *iobuf,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int *errcode,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ char **rt_start,
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len);
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len,
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_fieldwidth_info_t
**field_width);
This function pointer should point to a function that creates the input
records. Said function is the core of the input parser. Its behavior
is described in the text following this list.
@@ -32283,6 +32314,21 @@ If the concept of a ``record terminator'' makes sense,
then
data. Otherwise, @code{*rt_len} should be set to zero.
@command{gawk} makes its own copy of this data, so the
extension must manage this storage.
+
address@hidden const awk_fieldwidth_info_t **field_width
+If @code{field_width} is not @code{NULL}, then @code{*field_width} will be
initialized
+to @code{NULL}, and the function may set it to point to a structure
+supplying field width information to override the default
+field parsing mechanism. Note that this structure will not
+be copied by @command{gawk}; it must persist at least until the next call
+to @code{get_record} or @code{close_func}. Note also that @code{field_width}
will
+be @code{NULL} when @code{getline} is assigning the results to a variable, thus
+field parsing is not needed. If the parser does set @code{*field_width},
+then @command{gawk} will use this layout to parse the input record,
+and the @code{PROCINFO["FS"]} value will be @code{"API"} while this record
+is active in @code{$0}.
+The @code{awk_fieldwidth_info_t} data structure
+is described below.
@end table
The return value is the length of the buffer pointed to by
@@ -32341,6 +32387,50 @@ Register the input parser pointed to by
@code{input_parser} with
@command{gawk}.
@end table
+If you would like to override the default field parsing mechanism for a given
+record, then you must populate the @code{awk_fieldwidth_info_t} structure,
+which looks like this:
+
address@hidden
+typedef struct @{
+ awk_bool_t use_chars; /* false ==> use bytes */
+ size_t nf; /* number of fields in record (NF) */
+ struct awk_field_info @{
+ size_t skip; /* amount to skip before field starts */
+ size_t len; /* length of field */
+ @} fields[1]; /* actual dimension should be nf */
address@hidden awk_fieldwidth_info_t;
address@hidden example
+
+The fields are:
+
address@hidden @code
address@hidden awk_bool_t use_chars;
+Set this to @code{awk_true} if the field lengths are specified in terms
+of potentially multi-byte characters, and set it to @code{awk_false} if
+the lengths are in terms of bytes.
+Performance will be better if the values are supplied in
+terms of bytes.
+
address@hidden size_t nf;
+Set this to the number of fields in the input record, i.e. @code{NF}.
+
address@hidden struct awk_field_info fields[nf];
+This is a variable-length array whose actual dimension should be @code{nf}.
+For each field, the @code{skip} element should be set to the number
+of characters or bytes, as controlled by the @code{use_chars} flag,
+to skip before the start of this field. And the @code{len} element provides
+the length of the field. The values in @code{fields[0]} provide the information
+for the @code{$1} field, and so on through the @code{fields[nf-1]} element
containing the information for @code{$NF}.
address@hidden table
+
+A convenience macro @code{awk_fieldwidth_info_size(NF)} is provided to
+calculate the appropriate size of a variable-length
address@hidden structure containing @code{NF} fields. This can
+be used as an argument to @code{malloc} or in a union to allocate space
+statically. Please refer to the sample extension @code{readdir_test} for an
+example.
+
@node Output Wrappers
@subsubsection Customized Output Wrappers
@cindex customized output wrapper
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 7 +
doc/gawk.info | 1201 +++++++++++++++++++++++++++++--------------------------
doc/gawk.texi | 100 ++++-
doc/gawktexi.in | 100 ++++-
4 files changed, 839 insertions(+), 569 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, feature/api-parser, updated. gawk-4.1.0-2489-g7f6772a,
Andrew J. Schorr <=