[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, feature/better-index, updated. gawk-4.1.
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, feature/better-index, updated. gawk-4.1.0-3748-g5484684 |
|
Date: |
Wed, 24 Apr 2019 13:28:23 -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/better-index has been updated
via 54846844084efcbcee650187c274ba2cae0b94d0 (commit)
via 4edf1cc1bbeb56aaabb98761c448e7533f8ebf22 (commit)
via 9dfcaf5c979776f1f2bd80f48c7e4ded57a37e07 (commit)
via dfdf5031cea43a1d35b6cd513fa3c2692ef89a1c (commit)
from 3887537ae8fbe3e46782de5ebd350a508be202c9 (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=54846844084efcbcee650187c274ba2cae0b94d0
commit 54846844084efcbcee650187c274ba2cae0b94d0
Merge: dfdf503 4edf1cc
Author: Arnold D. Robbins <address@hidden>
Date: Wed Apr 24 20:28:17 2019 +0300
Merge branch 'master' into feature/better-index
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=dfdf5031cea43a1d35b6cd513fa3c2692ef89a1c
commit dfdf5031cea43a1d35b6cd513fa3c2692ef89a1c
Author: Arnold D. Robbins <address@hidden>
Date: Wed Apr 24 20:25:30 2019 +0300
More indexing.
diff --git a/doc/gawk.texi b/doc/gawk.texi
index ab2289a..e0f923e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -2167,10 +2167,10 @@ convincing me @emph{not} to title this @value{DOCUMENT}
@cite{How to Gawk Politely}.
Karl Berry helped significantly with the @TeX{} part of Texinfo.
address@hidden Hartholz, Marshall
address@hidden Hartholz, Elaine
address@hidden Schreiber, Bert
address@hidden Schreiber, Rita
address@hidden Hartholz @subentry Marshall
address@hidden Hartholz @subentry Elaine
address@hidden Schreiber @subentry Bert
address@hidden Schreiber @subentry Rita
I would like to thank Marshall and Elaine Hartholz of Seattle and
Dr.@: Bert and Rita Schreiber of Detroit for large amounts of quiet vacation
time in their homes, which allowed me to make significant progress on
@@ -2284,9 +2284,9 @@ and for being a role model to me for close to 30 years!
Having him as a reviewer is an exciting privilege. It has also
been extremely address@hidden
address@hidden Robbins, Miriam
address@hidden Robbins, Jean
address@hidden Robbins, Harry
address@hidden Robbins @subentry Miriam
address@hidden Robbins @subentry Jean
address@hidden Robbins @subentry Harry
@cindex G-d
I must thank my wonderful wife, Miriam, for her patience through
the many versions of this project, for her proofreading,
@@ -2362,7 +2362,7 @@ of the patterns, @command{awk} performs specified actions
on that line.
the end of the input files.
@cindex @command{awk} @subentry uses for
address@hidden programming address@hidden data-driven vs.@: procedural
address@hidden programming languages @subentry data-driven vs.@: procedural
@cindex @command{awk} programs
Programs in @command{awk} are different from programs in most other languages,
because @command{awk} programs are @dfn{data driven} (i.e., you describe
@@ -2614,7 +2614,7 @@ affect the execution of the @command{awk} program but it
does make
@subsection Executable @command{awk} Programs
@cindex @command{awk} programs
@cindex @code{#} (number sign) @subentry @code{#!} (executable scripts)
address@hidden Unix, @command{awk} scripts and
address@hidden Unix @subentry @command{awk} scripts and
@cindex number sign (@code{#}) @subentry @code{#!} (executable scripts)
Once you have learned @command{awk}, you may want to write self-contained
@@ -2934,7 +2934,7 @@ awk -F "" '@var{program}' @var{files} # correct
@end example
@noindent
address@hidden null strings in @command{gawk} arguments @subentry quoting and
address@hidden null strings @subentry in @command{gawk} arguments, quoting and
Don't use this:
@example
@@ -4089,7 +4089,7 @@ at their beginning. @xref{Changing The Namespace}, for
more information.
@itemx @option{--load} @var{ext}
@cindex @option{-l} option
@cindex @option{--load} option
address@hidden loading, extensions
address@hidden loading extensions
Load a dynamic extension named @var{ext}. Extensions
are stored as system shared libraries.
This option searches for the library using the @env{AWKLIBPATH}
@@ -4136,8 +4136,8 @@ if @command{gawk} is not compiled to use the GNU MPFR and
MP libraries
@itemx @option{--non-decimal-data}
@cindex @option{-n} option
@cindex @option{--non-decimal-data} option
address@hidden hexadecimal address@hidden enabling interpretation of
address@hidden octal address@hidden enabling interpretation of
address@hidden hexadecimal values, enabling interpretation of
address@hidden octal values, enabling interpretation of
@cindex troubleshooting @subentry @code{--non-decimal-data} option
Enable automatic interpretation of octal and hexadecimal
values in input data
@@ -4191,7 +4191,7 @@ be used to cancel the effect of an earlier @option{-s}
option
@itemx @address@hidden@var{file}]
@cindex @option{-p} option
@cindex @option{--profile} option
address@hidden @command{awk} profiling, enabling
address@hidden @command{awk} @subentry profiling, enabling
Enable profiling of @command{awk} programs
(@pxref{Profiling}).
Implies @option{--no-optimize}.
@@ -4357,6 +4357,7 @@ the command line that follow the program text are entered
into the
command line looking for options.
@cindex @env{POSIXLY_CORRECT} environment variable
address@hidden environment variables @subentry @env{POSIXLY_CORRECT}
@cindex lint checking @subentry @env{POSIXLY_CORRECT} environment variable
@cindex POSIX mode
If the environment variable @env{POSIXLY_CORRECT} exists,
@@ -4523,6 +4524,7 @@ behaves.
@node AWKPATH Variable
@subsection The @env{AWKPATH} Environment Variable
@cindex @env{AWKPATH} environment variable
address@hidden environment variables @subentry @env{AWKPATH}
@cindex directories @subentry searching @subentry for source files
@cindex search paths @subentry for source files
@cindex differences in @command{awk} and @command{gawk} @subentry
@env{AWKPATH} environment variable
@@ -4609,6 +4611,7 @@ found, and @command{gawk} no longer needs to use
@env{AWKPATH}.
@node AWKLIBPATH Variable
@subsection The @env{AWKLIBPATH} Environment Variable
@cindex @env{AWKLIBPATH} environment variable
address@hidden environment variables @subentry @env{AWKLIBPATH}
@cindex directories @subentry searching @subentry for loadable extensions
@cindex search paths @subentry for loadable extensions
@cindex differences in @command{awk} and @command{gawk} @subentry
@code{AWKLIBPATH} environment variable
@@ -4769,6 +4772,7 @@ This @value{SECTION} describes a feature that is specific
to @command{gawk}.
@cindex at-sign (@code{@@}) @subentry @code{@@include} directive
@cindex file inclusion, @code{@@include} directive
@cindex including files, @code{@@include} directive
address@hidden @code{@@include} directive @sortas{include directive}
The @code{@@include} keyword can be used to read external @command{awk} source
files. This gives you the ability to split large @command{awk} source files
into smaller, more manageable pieces, and also lets you reuse common
@command{awk}
@@ -4896,8 +4900,9 @@ This @value{SECTION} describes a feature that is specific
to @command{gawk}.
@cindex @code{@@} (at-sign) @subentry @code{@@load} directive
@cindex at-sign (@code{@@}) @subentry @code{@@load} directive
address@hidden loading extensions, @code{@@load} directive
address@hidden loading extensions @subentry @code{@@load} directive
@cindex extensions @subentry loadable @subentry loading, @code{@@load}
directive
address@hidden @code{@@load} directive @sortas{load directive}
The @code{@@load} keyword can be used to read external @command{awk} extensions
(stored as system shared libraries).
This allows you to link in compiled code that may offer superior
@@ -5160,7 +5165,7 @@ regular expressions work, we present more complicated
instances.
@node Regexp Usage
@section How to Use Regular Expressions
address@hidden patterns @subentry regular expressions as
address@hidden patterns @subentry regexp constants as
@cindex regular expressions @subentry as patterns
A regular expression can be used as a pattern by enclosing it in
slashes. Then the regular expression is tested against the
@@ -5181,13 +5186,13 @@ $ @kbd{awk '/li/ @{ print $2 @}' mail-list}
@cindex operators @subentry string-matching
@c @cindex operators, @code{~}
@cindex string-matching operators
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@c @cindex operators, @code{!~}
@cindex @code{if} statement @subentry use of regexps in
address@hidden @code{while} statement, use of regexps in
address@hidden @code{while} statement @subentry use of regexps in
@cindex @address@hidden statement @subentry use of regexps in
@c @cindex statements, @code{if}
@c @cindex statements, @code{while}
@@ -5287,6 +5292,7 @@ all the escape sequences used in @command{awk} and
what they represent. Unless noted otherwise, all these escape
sequences apply to both string constants and regexp constants:
address@hidden ASCII
@table @code
@item \\
A literal backslash, @samp{\}.
@@ -5634,7 +5640,7 @@ The condition in the following example is not true:
if ("line1\nLINE 2" ~ /1$/) @dots{}
@end example
address@hidden @code{.} (period) @subentry regexp operator
address@hidden @code{.} (period), regexp operator
@cindex period (@code{.}), regexp operator
@item @code{.} (period)
This matches any single character,
@@ -5644,6 +5650,7 @@ concatenation, we can make a regular expression such as
@samp{U.A}, which
matches any three-character sequence that begins with @samp{U} and ends
with @samp{A}.
address@hidden POSIX mode
@cindex POSIX @command{awk} @subentry period (@code{.}), using
In strict POSIX mode (@pxref{Options}),
@samp{.} does not match the @sc{nul}
@@ -5759,7 +5766,7 @@ Matches @samp{whhy}, @samp{whhhy}, and so on.
@end table
@end table
address@hidden precedence, regexp operators
address@hidden precedence @subentry regexp operators
@cindex regular expressions @subentry operators @subentry precedence of
In regular expressions, the @samp{*}, @samp{+}, and @samp{?} operators,
as well as the braces @address@hidden and @address@hidden,
@@ -5940,6 +5947,7 @@ depends on various factors out of our control.
@c Thanks to
@c Date: Tue, 01 Jul 2014 07:39:51 +0200
@c From: Hermann Peifer <address@hidden>
address@hidden ASCII
Some utilities that match regular expressions provide a nonstandard
@samp{[:ascii:]} character class; @command{awk} does not. However, you
can simulate such a construct using @samp{[\x00-\x7F]}. This matches
@@ -6044,7 +6052,7 @@ and also @pxref{Field Separators}).
@cindex regular expressions @subentry computed
@cindex regular expressions @subentry dynamic
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -6096,7 +6104,7 @@ two characters @samp{\} and @samp{*}.
@cindex troubleshooting @subentry regexp constants vs.@: string constants
@cindex regexp constants @subentry vs.@: string constants
address@hidden string constants, vs.@: regexp constants
address@hidden string @subentry constants @subentry vs.@: regexp constants
Given that you can use both regexp and string constants to describe
regular expressions, which should you use? The answer is ``regexp
constants,'' for several reasons:
@@ -6263,7 +6271,7 @@ For example, @code{/stow\>/} matches @samp{stow} but not
@samp{stowaway}.
@c @cindex operators, @code{\y} (@command{gawk})
@cindex backslash (@code{\}) @subentry @code{\y} operator (@command{gawk})
@cindex @code{\} (backslash) @subentry @code{\y} operator (@command{gawk})
address@hidden word address@hidden matching
address@hidden word boundaries, matching
@item \y
Matches the empty string at either the beginning or the
end of a word (i.e., the word address@hidden). For example, @samp{\yballs?\y}
@@ -6324,7 +6332,7 @@ GNU operators, but this was deemed too confusing. The
current
method of using @samp{\y} for the GNU @samp{\b} appears to be the
lesser of two evils.
address@hidden regular expressions @subentry @command{gawk} @subentry
command-line options
address@hidden regular expressions @subentry @command{gawk}, command-line
options
@cindex @command{gawk} @subentry command-line options, regular expressions and
The various command-line options
(@pxref{Options})
@@ -6398,7 +6406,7 @@ This works in any POSIX-compliant @command{awk}.
@cindex @command{gawk} @subentry regular expressions @subentry case sensitivity
@cindex case sensitivity @subentry @command{gawk}
@cindex differences in @command{awk} and @command{gawk} @subentry regular
expressions
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -6736,7 +6744,7 @@ even if the last character in the file is not the
character in @code{RS}.
@cindex empty strings @seeentry{null strings}
@cindex null strings
address@hidden strings, empty @seeentry{null strings}
address@hidden strings @subentry empty @seeentry{null strings}
The empty string @code{""} (a string without any characters)
has a special meaning
as the value of @code{RS}. It means that records are separated
@@ -6966,7 +6974,7 @@ simple @command{awk} programs so powerful.
@cindex field operator @code{$}
@cindex @code{$} (dollar sign) @subentry @code{$} field operator
@cindex dollar sign (@code{$}) @subentry @code{$} field operator
address@hidden field address@hidden dollar sign as
address@hidden field operators, dollar sign as
You use a dollar sign (@samp{$})
to refer to a field in an @command{awk} program,
followed by the number of the field you want. Thus, @code{$1}
@@ -7217,7 +7225,7 @@ The intervening field, @code{$5}, is created with an
empty value
and @code{NF} is updated with the value six.
@cindex dark corner @subentry @code{NF} variable, decrementing
address@hidden @code{NF} variable, decrementing
address@hidden @code{NF} variable @subentry decrementing
Decrementing @code{NF} throws away the values of the fields
after the new value of @code{NF} and recomputes @code{$0}.
@value{DARKCORNER}
@@ -7658,7 +7666,7 @@ encrypted or shadow password. (A shadow password is
indicated by the
presence of a single @samp{x} in the second field.) A password file
entry might look like this:
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Arnold
@example
arnold:x:2076:10:Arnold Robbins:/home/arnold:/bin/bash
@end example
@@ -8277,7 +8285,7 @@ a page of the file. To do this, just set the variable
@code{RS} to
other character could equally well be used, as long as it won't be part
of the data in a record.
address@hidden @code{RS} variable, multiline records and
address@hidden @code{RS} variable @subentry multiline records and
Another technique is to have blank lines separate records. By a special
dispensation, an empty string as the value of @code{RS} indicates that
records are separated by one or more blank lines. When @code{RS} is set
@@ -8795,9 +8803,9 @@ bletch
@noindent
the program might produce:
address@hidden Robbins, Bill
address@hidden Robbins, Miriam
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Bill
address@hidden Robbins @subentry Miriam
address@hidden Robbins @subentry Arnold
@example
foo
bar
@@ -9286,6 +9294,7 @@ from the default input stream, from a file, or from a
pipe or coprocess.
Use @address@hidden, "READ_TIMEOUT"]} to cause reads to time out
for @var{file}.
address@hidden POSIX mode
@item
Directories on the command line are fatal for standard @command{awk};
@command{gawk} ignores them if not in POSIX mode.
@@ -9380,7 +9389,7 @@ current record (such as @code{$1}), variables, or any
@command{awk}
expression. Numeric values are converted to strings and then printed.
@cindex records @subentry printing
address@hidden lines, blank, printing
address@hidden lines @subentry blank, printing
@cindex text @subentry printing
The simple statement @samp{print} with no items is equivalent to
@samp{print $0}: it prints the entire current record. To print a blank
@@ -9443,7 +9452,7 @@ $ @kbd{awk '@{ print $1, $2 @}' inventory-shipped}
@dots{}
@end example
address@hidden @code{print} statement @subentry commas @subentry omitting
address@hidden @code{print} statement @subentry commas, omitting
@cindex troubleshooting @subentry @code{print} statement, omitting commas
A common mistake in using the @code{print} statement is to omit the comma
between two items. This often has the effect of making the items run
@@ -9584,7 +9593,7 @@ runs together on a single line.
@node OFMT
@section Controlling Numeric Output with @code{print}
@cindex numeric @subentry output format
address@hidden address@hidden numeric output
address@hidden formats, numeric output
When printing numeric values with the @code{print} statement,
@command{awk} internally converts each number to a string of characters
and prints that string. @command{awk} uses the @code{sprintf()} function
@@ -9618,7 +9627,7 @@ $ @kbd{awk 'BEGIN @{}
@noindent
@cindex dark corner @subentry @code{OFMT} variable
@cindex POSIX @command{awk} @subentry @code{OFMT} variable and
address@hidden @code{OFMT} variable, POSIX @command{awk} and
address@hidden @code{OFMT} variable @subentry POSIX @command{awk} and
According to the POSIX standard, @command{awk}'s behavior is undefined
if @code{OFMT} contains anything but a floating-point conversion specification.
@value{DARKCORNER}
@@ -9857,7 +9866,7 @@ the IEEE standard. Further details are provided in
@subsection Modifiers for @code{printf} Formats
@cindex @code{printf} statement @subentry modifiers
address@hidden address@hidden in format specifiers
address@hidden modifiers, in format specifiers
A format specification can also include @dfn{modifiers} that can control
how much of the item's value is printed, as well as how much space it gets.
The modifiers come between the @samp{%} and the format-control letter.
@@ -10164,8 +10173,8 @@ Redirections in @command{awk} are written just like
redirections in shell
commands, except that they are written inside the @command{awk} program.
@c the commas here are part of the see also
address@hidden @code{print} statement @address@hidden of output}
address@hidden @code{printf} statement @address@hidden of output}
address@hidden @code{print} statement @seealso{redirection of output}
address@hidden @code{printf} statement @seealso{redirection of output}
There are four forms of output redirection: output to a file, output
appended to a file, output through a pipe to another command, and output
to a coprocess. We show them all for the @code{print} statement,
@@ -10562,7 +10571,7 @@ above two, does actually close the given file
descriptor.
@node Special Network
@subsection Special Files for Network Communications
@cindex networks @subentry support for
address@hidden TCP/IP, support for
address@hidden TCP/IP @subentry support for
@command{gawk} programs
can open a two-way
@@ -10593,6 +10602,7 @@ special @value{FN}s that @command{gawk} provides:
@itemize @value{BULLET}
@cindex compatibility mode (@command{gawk}) @subentry file names
@cindex file names @subentry in compatibility mode
address@hidden POSIX mode
@item
Recognition of the @value{FN}s for the three standard preopened
files is disabled only in POSIX mode.
@@ -10795,7 +10805,7 @@ which describes it in more detail and gives an example.
@cindex dark corner @subentry @code{close()} function
@cindex @code{close()} function @subentry return value
address@hidden return address@hidden @code{close()} function
address@hidden return value, @code{close()} function
@cindex differences in @command{awk} and @command{gawk} @subentry
@code{close()} function
@cindex Unix @command{awk} @subentry @code{close()} function and
@@ -10841,6 +10851,7 @@ if it fails.
@end multitable
@end float
address@hidden POSIX mode
The POSIX standard is very vague; it says that @code{close()}
returns zero on success and a nonzero value otherwise. In general,
different implementations vary in what they report when closing
@@ -10861,7 +10872,7 @@ when closing a pipe.
@cindex dark corner @subentry @code{close()} function
@cindex @code{close()} function @subentry return value
address@hidden return address@hidden @code{close()} function
address@hidden return value, @code{close()} function
@cindex differences in @command{awk} and @command{gawk} @subentry
@code{close()} function
@cindex Unix @command{awk} @subentry @code{close()} function and
@@ -10907,6 +10918,7 @@ if it fails.
@end multitable
@end float
address@hidden POSIX mode
The POSIX standard is very vague; it says that @code{close()}
returns zero on success and a nonzero value otherwise. In general,
different implementations vary in what they report when closing
@@ -11116,7 +11128,7 @@ have different forms, but are internally stored in an
identical manner.
@subsubsection Numeric and String Constants
@cindex constants @subentry numeric
address@hidden numeric constants
address@hidden numeric @subentry constants
A @dfn{numeric constant} stands for a number. This number can be an
integer, a decimal fraction, or a number in scientific (exponential)
address@hidden internal representation of all numbers,
@@ -11132,7 +11144,7 @@ have the same value:
1050e-1
@end example
address@hidden string constants
address@hidden string @subentry constants
@cindex constants @subentry string
A @dfn{string constant} consists of a sequence of characters enclosed in
double quotation marks. For example:
@@ -11144,6 +11156,7 @@ double quotation marks. For example:
@noindent
@cindex differences in @command{awk} and @command{gawk} @subentry strings
@cindex strings @subentry length limitations
address@hidden ASCII
represents the string whose contents are @samp{parrot}. Strings in
@command{gawk} can be of any length, and they can contain any of the possible
eight-bit ASCII characters, including ASCII @sc{nul} (character code zero).
@@ -11198,6 +11211,7 @@ $ @kbd{gawk 'BEGIN @{ print "hello, \}
@print{} hello, world
@end example
address@hidden POSIX mode
In POSIX mode (@pxref{Options}), @command{gawk} does not
allow escaped newlines. Otherwise, it behaves as just described.
@@ -11345,7 +11359,7 @@ $ @kbd{gawk 'BEGIN @{ printf "0x11 is <%s>\n", 0x11 @}'}
@subsubsection Regular Expression Constants
@cindex regexp constants
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -11748,7 +11762,7 @@ concatenated together. The resulting string is
converted back to the
number 23, to which 4 is then added.
@cindex null strings @subentry converting numbers to strings
address@hidden type conversion
address@hidden type @subentry conversion
If, for some reason, you need to force a number to be converted to a
string, concatenate that number with the empty string, @code{""}.
To force a string to be converted to a number, add zero to that string.
@@ -11880,6 +11894,7 @@ the decimal point separator. In the normal @code{"C"}
locale, @command{gawk}
treats @samp{4,321} as 4, while in the Danish locale, it's treated
as the full number including the fractional part, 4.321.
address@hidden POSIX mode
Some earlier versions of @command{gawk} fully complied with this aspect
of the standard. However, many users in non-English locales complained
about this behavior, because their data used a period as the decimal
@@ -12049,7 +12064,7 @@ For maximum portability, do not use the @samp{**}
operator.
@author Brian Kernighan
@end quotation
address@hidden string operators
address@hidden string @subentry operators
@cindex operators @subentry string
@cindex concatenating
There is only one string operation: concatenation. It does not have a
@@ -12752,8 +12767,7 @@ the string constant @code{"0"} is actually true,
because it is non-null.
@cindex expressions, matching @seeentry{comparison expressions}
@cindex matching, expressions @seeentry{comparison expressions}
@cindex relational operators @seeentry{comparison operators}
address@hidden operators, relational @address@hidden comparison}
address@hidden variable typing
address@hidden operators, relational @seeentry{operators, comparison}
@cindex variables @subentry types of @subentry comparison expressions and
Unlike in other programming languages, in @command{awk} variables do not have a
fixed type. Instead, they can be either a number or a string, depending
@@ -13062,6 +13076,7 @@ $ @kbd{echo hello 37 | gawk '@{ print typeof($1),
typeof($2) @}'}
@node Comparison Operators
@subsubsection Comparison Operators
address@hidden operators @subentry comparison
@dfn{Comparison expressions} compare strings or numbers for
relationships such as equality. They are written using @dfn{relational
@@ -13080,7 +13095,7 @@ operators}, which are a superset of those in C.
@cindex equals sign (@code{=}) @subentry @code{==} operator
@cindex @code{!} (exclamation point) @subentry @code{!=} operator
@cindex exclamation point (@code{!}) @subentry @code{!=} operator
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -13194,7 +13209,7 @@ x ~ /foo/
has the value one if @code{x} contains @samp{foo}, such as
@code{"Oh, what a fool am I!"}.
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -13232,6 +13247,7 @@ address@hidden, string comparison is supposed to behave
the same way as if the strings were compared with the C @code{strcoll()}
function.}
address@hidden POSIX mode
Because this behavior differs considerably from existing practice,
@command{gawk} only implemented it when in POSIX mode (@pxref{Options}).
Here is an example to illustrate the difference, in an @code{en_US.UTF-8}
@@ -13263,6 +13279,7 @@ a <= b && a >= b
@end example
@end quotation
address@hidden POSIX mode
As of @value{PVERSION} 4.2, @command{gawk} continues to use locale
collating order for @code{<}, @code{<=}, @code{>}, and @code{>=} only
in POSIX mode.
@@ -13602,7 +13619,7 @@ $ @kbd{awk -f matchit.awk}
@node Precedence
@section Operator Precedence (How Operators Nest)
@cindex precedence
address@hidden operators @subentry precedence
address@hidden operators @subentry precedence of
@dfn{Operator precedence} determines how operators are grouped when
different operators appear close by in one expression. For example,
@@ -13736,7 +13753,7 @@ parentheses. Such combinations (e.g., @samp{print foo
> a ? b : c})
result in syntax errors.
The correct way to write this statement is @samp{print foo > (a ? b : c)}.
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -13971,7 +13988,7 @@ The empty pattern matches every input record.
@node Regexp Patterns
@subsection Regular Expressions as Patterns
address@hidden patterns @subentry regular expressions as
address@hidden patterns @subentry regexp constants as
@cindex regular expressions @subentry as patterns
Regular expressions are one of the first kinds of patterns presented
@@ -14016,7 +14033,7 @@ whose first field is precisely @samp{li}:
@cindex @code{/} (forward slash) @subentry patterns and
@cindex forward slash (@code{/}) @subentry patterns and
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -14186,7 +14203,7 @@ $ @kbd{echo Yes | gawk '(/1/,/2/) || /Yes/'}
@error{} gawk: cmd. line:1: ^ syntax error
@end example
address@hidden range patterns, line continuation and
address@hidden range patterns @subentry line continuation and
@cindex dark corner @subentry range patterns, line continuation and
As a minor point of interest, although it is poor style,
POSIX allows you to put a newline after the comma in
@@ -14611,7 +14628,7 @@ For deleting array elements.
control the flow of execution in @command{awk} programs. Most of
@command{awk}'s
control statements are patterned after similar statements in C.
address@hidden compound address@hidden control statements and
address@hidden compound statements, control statements and
@cindex statements @subentry compound, control statements and
@cindex body @subentry in actions
@cindex @address@hidden@}} (braces) @subentry statements, grouping
@@ -14883,7 +14900,7 @@ while (@var{condition}) @{
@}
@end example
address@hidden loops @subentry @code{continue} statements and
address@hidden loops @subentry @code{continue} statement and
@noindent
The only exception is when the @code{continue} statement
(@pxref{Continue Statement}) is used
@@ -15882,6 +15899,7 @@ while the program runs.
@item PROCINFO["platform"]
@cindex platform running on
address@hidden @code{PROCINFO} array @subentry platform running on
This element gives a string indicating the platform for which
@command{gawk} was compiled. The value will be one of the following:
@@ -15925,7 +15943,7 @@ Assigning a new value to this element changes the
default.
The value of the @code{getuid()} system call.
@item PROCINFO["version"]
address@hidden version of @command{gawk}
address@hidden version of @subentry @command{gawk}
@cindex @command{gawk} version
The version of @command{gawk}.
@end table
@@ -15937,10 +15955,10 @@ if your version of @command{gawk} supports
arbitrary-precision arithmetic
@table @code
@item PROCINFO["gmp_version"]
address@hidden version of GNU MP library
address@hidden version of @subentry GNU MP library
The version of the GNU MP library.
address@hidden version of GNU MPFR library
address@hidden version of @subentry GNU MPFR library
@item PROCINFO["mpfr_version"]
The version of the GNU MPFR library.
@@ -15960,7 +15978,7 @@ of @command{gawk} supports dynamic loading of extension
functions
@table @code
@item PROCINFO["api_major"]
address@hidden version of @command{gawk} extension API
address@hidden version of @subentry @command{gawk} extension API
@cindex extension API @subentry version number
The major version of the extension API.
@@ -16771,7 +16789,7 @@ that have not been assigned any value as well as
elements that have been
deleted (@pxref{Delete}).
@cindex non-existent array elements
address@hidden arrays @subentry elements that don't exist
address@hidden arrays @subentry elements @subentry that don't exist
@quotation NOTE
A reference to an element that does not exist @emph{automatically} creates
that array element, with the null string as its value. (In some cases,
@@ -17071,7 +17089,7 @@ to use for comparison of array elements. This advanced
feature
is described later in @ref{Array Sorting}.
@end itemize
address@hidden @code{PROCINFO} @subentry values of @code{sorted_in}
address@hidden @code{PROCINFO} array @subentry values of @code{sorted_in}
The following special values for @code{PROCINFO["sorted_in"]} are available:
@table @code
@@ -17381,7 +17399,7 @@ if (4 in foo)
@end group
@end example
address@hidden lint checking @subentry array elements
address@hidden lint checking @subentry array subscripts
It is not an error to delete an element that does not exist.
However, if @option{--lint} is provided on the command line
(@pxref{Options}),
@@ -17428,7 +17446,7 @@ out an array:@footnote{Thanks to Michael Brennan for
pointing this out.}
split("", array)
@end example
address@hidden @code{split()} function, array address@hidden deleting
address@hidden @code{split()} function @subentry array elements, deleting
The @code{split()} function
(@pxref{String Functions})
clears out the target array first. This call asks it to split
@@ -17463,7 +17481,7 @@ languages, including @command{awk}) to refer to an
element of a
two-dimensional array named @code{grid} is with
@address@hidden,@var{y}]}.
address@hidden @code{SUBSEP} variable, multidimensional arrays and
address@hidden @code{SUBSEP} variable @subentry multidimensional arrays and
Multidimensional arrays are supported in @command{awk} through
concatenation of indices into one string.
@command{awk} converts the indices into strings
@@ -17935,7 +17953,7 @@ two arguments 11 and 10.
@node Numeric Functions
@subsection Numeric Functions
address@hidden numeric functions
address@hidden numeric @subentry functions
The following list describes all of
the built-in functions that work with numbers.
@@ -18304,7 +18322,7 @@ and the third argument must be assignable.
@item @code{index(@var{in}, @var{find})}
@cindexawkfunc{index}
address@hidden search in string
address@hidden search for substring
@cindex find substring in string
Search the string @var{in} for the first occurrence of the string
@var{find}, and return the position in characters where that occurrence
@@ -18326,7 +18344,7 @@ constant as an expression meaning @samp{$0 ~ /regexp/}.
@value{DARKCORNER}
@item @code{length(address@hidden@code{)}
@cindexawkfunc{length}
address@hidden string length
address@hidden string @subentry length
@cindex length of string
Return the number of characters in @var{string}. If
@var{string} is a number, the length of the digit string representing
@@ -18402,7 +18420,7 @@ If @option{--posix} is supplied, using an array
argument is a fatal error
@item @code{match(@var{string}, @var{regexp}} address@hidden, @address@hidden)}
@cindexawkfunc{match}
address@hidden string, regular expression match
address@hidden string @subentry regular expression match
@cindex match regexp in string
Search @var{string} for the
longest, leftmost substring matched by the regular expression
@@ -18423,9 +18441,11 @@ functions that work with regular expressions, such as
for @code{match()}, the order is the same as for the @samp{~} operator:
@address@hidden ~ @var{regexp}}.
address@hidden @code{RSTART} variable, @code{match()} function and
address@hidden @code{RLENGTH} variable, @code{match()} function and
address@hidden @code{match()} function, @code{RSTART}/@code{RLENGTH} variables
address@hidden @code{RSTART} variable @subentry @code{match()} function and
address@hidden @code{RLENGTH} variable @subentry @code{match()} function and
address@hidden @code{match()} function @subentry @code{RSTART}/@code{RLENGTH}
variables
address@hidden @code{match()} function @subentry side effects
address@hidden side effects @subentry @code{match()} function
The @code{match()} function sets the predefined variable @code{RSTART} to
the index. It also sets the predefined variable @code{RLENGTH} to the
length in characters of the matched substring. If no match is found,
@@ -18573,7 +18593,7 @@ split("cul-de-sac", a, "-", seps)
@end example
@noindent
address@hidden strings splitting @subentry example
address@hidden strings @subentry splitting, example
splits the string @code{"cul-de-sac"} into three fields using @samp{-} as the
separator. It sets the contents of the array @code{a} as follows:
@@ -18629,6 +18649,7 @@ If @var{string} does not match @var{fieldsep} at all
(but is not null),
@var{array} has one element only. The value of that element is the original
@var{string}.
address@hidden POSIX mode
In POSIX mode (@pxref{Options}), the fourth argument is not allowed.
@item @code{sprintf(@var{format}, @var{expression1}, @dots{})}
@@ -18748,6 +18769,8 @@ an @samp{&}:
@cindex @code{sub()} function @subentry arguments of
@cindex @code{gsub()} function @subentry arguments of
address@hidden side effects @subentry @code{sub()} function
address@hidden side effects @subentry @code{gsub()} function
As mentioned, the third argument to @code{sub()} must
be a variable, field, or array element.
Some versions of @command{awk} allow the third argument to
@@ -20159,7 +20182,6 @@ Return the bitwise AND of the arguments. There must be
at least two.
Return the bitwise complement of @var{val}.
@cindexgawkfunc{lshift}
address@hidden left shift
@item @code{lshift(@var{val}, @var{count})}
Return the value of @var{val}, shifted left by @var{count} bits.
@@ -20169,7 +20191,6 @@ Return the value of @var{val}, shifted left by
@var{count} bits.
Return the bitwise OR of the arguments. There must be at least two.
@cindexgawkfunc{rshift}
address@hidden right shift
@item @code{rshift(@var{val}, @var{count})}
Return the value of @var{val}, shifted right by @var{count} bits.
@@ -20190,6 +20211,7 @@ Here is a user-defined function (@pxref{User-defined})
that illustrates the use of these functions:
@cindex @code{bits2str()} user-defined function
address@hidden user-defined @subentry function @subentry @code{bits2str()}
@cindex @code{testbits.awk} program
@example
@group
@@ -20428,8 +20450,8 @@ that traverses every element of an array of arrays
Return a true value if @var{x} is an array. Otherwise, return false.
@cindexgawkfunc{typeof}
address@hidden variable type
address@hidden type, of variable
address@hidden variable type, @code{typeof()} function (@command{gawk})
address@hidden type @subentry of variable, @code{typeof()} function
(@command{gawk})
@item typeof(@var{x})
Return one of the following strings, depending upon the type of @var{x}:
@@ -20525,7 +20547,7 @@ Optional parameters are enclosed in square brackets ([
]):
@table @asis
@cindexgawkfunc{bindtextdomain}
address@hidden set directory of message catalogs
address@hidden set @subentry directory of message catalogs
@item @code{bindtextdomain(@var{directory}} address@hidden,} @address@hidden)}
Set the directory in which
@command{gawk} will look for message translation files, in case they
@@ -20560,7 +20582,7 @@ The default value for @var{category} is
@code{"LC_MESSAGES"}.
@node User-defined
@section User-Defined Functions
address@hidden user-defined functions
address@hidden user-defined @subentry functions
@cindex functions @subentry user-defined
Complicated @command{awk} programs can often be simplified by defining
your own functions. User-defined functions can be called just like
@@ -20607,7 +20629,7 @@ The definition of a function named @var{name} looks
like this:
@cindex names @subentry functions
@cindex functions @subentry names of
address@hidden namespace issues, functions
address@hidden namespace issues @subentry functions
@noindent
Here, @var{name} is the name of the function to define. A valid function
name is like a valid variable name: a sequence of letters, digits, and
@@ -20797,6 +20819,7 @@ already empty:
@c 8/2014: Thanks to Mike Brennan for the improved formulation
@cindex @code{rev()} user-defined function
address@hidden user-defined @subentry function @subentry @code{rev()}
@example
function rev(str)
@{
@@ -20823,6 +20846,7 @@ The following example uses the built-in
@code{strftime()} function
to create an @command{awk} version of @code{ctime()}:
@cindex @code{ctime()} user-defined function
address@hidden user-defined @subentry function @subentry @code{ctime()}
@example
@c file eg/lib/ctime.awk
# ctime.awk
@@ -21180,7 +21204,7 @@ don't like the warning, fix your code! It's incorrect,
after all.)
@node Return Statement
@subsection The @code{return} Statement
address@hidden @code{return} address@hidden user-defined functions
address@hidden @code{return} statement, user-defined functions
As seen in several earlier examples,
the body of a user-defined function can contain a @code{return} statement.
@@ -22112,6 +22136,7 @@ be tested with @command{gawk} and the results compared
to the built-in
@cindex assertions
@cindex @code{assert()} function (C library)
address@hidden C library functions @subentry @code{assert()}
@cindex libraries of @command{awk} functions @subentry assertions
@cindex functions @subentry library @subentry assertions
@cindex @command{awk} programs @subentry lengthy @subentry assertions
@@ -22145,6 +22170,7 @@ prog.c:5: assertion failed: a <= 5 && b >= 17.1
@end example
@cindex @code{assert()} user-defined function
address@hidden user-defined @subentry function @subentry @code{assert()}
The C language makes it possible to turn the condition into a string for use
in printing the diagnostic message. This is not possible in @command{awk}, so
this @code{assert()} function also requires a string version of the condition
@@ -22240,7 +22266,7 @@ with an @code{exit} statement.
@cindex functions @subentry library @subentry rounding numbers
@cindex @code{print} statement @subentry @code{sprintf()} function and
@cindex @code{printf} statement @subentry @code{sprintf()} function and
address@hidden @code{sprintf()} function, @code{print}/@code{printf} statements
and
address@hidden @code{sprintf()} function @subentry @code{print}/@code{printf}
statements and
The way @code{printf} and @code{sprintf()}
(@pxref{Printf})
perform rounding often depends upon the system's C @code{sprintf()}
@@ -22254,6 +22280,7 @@ traditional rounding; it might be useful if your
@command{awk}'s @code{printf}
does unbiased rounding:
@cindex @code{round()} user-defined function
address@hidden user-defined @subentry function @subentry @code{round()}
@example
@c file eg/lib/round.awk
# round.awk --- do normal rounding
@@ -22313,6 +22340,7 @@ for randomness by showing no structure.''
It is easily programmed, in less than 10 lines of @command{awk} code:
@cindex @code{cliff_rand()} user-defined function
address@hidden user-defined @subentry function @subentry @code{cliff_rand()}
@example
@c file eg/lib/cliff_rand.awk
# cliff_rand.awk --- generate Cliff random numbers
@@ -22362,8 +22390,11 @@ Both functions are written very nicely in
@command{awk}; there is no real
reason to build them into the @command{awk} interpreter:
@cindex @code{ord()} user-defined function
address@hidden user-defined @subentry function @subentry @code{ord()}
@cindex @code{chr()} user-defined function
address@hidden user-defined @subentry function @subentry @code{chr()}
@cindex @code{_ord_init()} user-defined function
address@hidden user-defined @subentry function @subentry @code{_ord_init()}
@example
@c file eg/lib/ord.awk
# ord.awk --- do ord and chr
@@ -22490,6 +22521,7 @@ assumption, as the array was likely created with
@code{split()}
(@pxref{String Functions}):
@cindex @code{join()} user-defined function
address@hidden user-defined @subentry function @subentry @code{join()}
@example
@c file eg/lib/join.awk
# join.awk --- join an array into a string
@@ -22548,6 +22580,7 @@ with preformatted time information. It returns a
string with the current
time formatted in the same way as the @command{date} utility:
@cindex @code{getlocaltime()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getlocaltime()}
@example
@c file eg/lib/gettime.awk
# getlocaltime.awk --- get the time of day in a usable format
@@ -22659,6 +22692,7 @@ The following function, based on a suggestion by Denis
Shirokov,
reads the entire contents of the named file in one shot:
@cindex @code{readfile()} user-defined function
address@hidden user-defined @subentry function @subentry @code{readfile()}
@example
@c file eg/lib/readfile.awk
# readfile.awk --- read an entire file at once
@@ -22871,7 +22905,9 @@ supplied in the ``main'' program, @code{endfile()} is
called first. Once
again, the value of multiple @code{BEGIN} and @code{END} rules should be clear.
@cindex @code{beginfile()} user-defined function
address@hidden user-defined @subentry function @subentry @code{beginfile()}
@cindex @code{endfile()} user-defined function
address@hidden user-defined @subentry function @subentry @code{endfile()}
If the same @value{DF} occurs twice in a row on the command line, then
@code{endfile()} and @code{beginfile()} are not executed at the end of the
first pass and at the beginning of the second pass.
@@ -22969,6 +23005,7 @@ and then start over with it from the top.
For lack of a better name, we'll call the function @code{rewind()}:
@cindex @code{rewind()} user-defined function
address@hidden user-defined @subentry function @subentry @code{rewind()}
@example
@c file eg/lib/rewind.awk
# rewind.awk --- rewind the current file and start over
@@ -23043,7 +23080,7 @@ $ @kbd{gawk -f rewind.awk -f test.awk data }
@subsection Checking for Readable @value{DDF}s
@cindex troubleshooting @subentry readable data files
address@hidden readable data address@hidden checking
address@hidden readable data files, checking
@cindex files @subentry skipping
Normally, if you give @command{awk} a @value{DF} that isn't readable,
it stops with a fatal error. There are times when you might want to
@@ -23082,7 +23119,7 @@ BEGIN @{
@c endfile
@end example
address@hidden troubleshooting @subentry @code{getline} function
address@hidden troubleshooting @subentry @code{getline} command
This works, because the @code{getline} won't be fatal.
Removing the element from @code{ARGV} with @code{delete}
skips the file (because it's no longer in the list).
@@ -23236,6 +23273,7 @@ The first occurrence on the command line of either
@option{--} or a
string that does not begin with @samp{-} ends the options.
@cindex @code{getopt()} function (C library)
address@hidden C library functions @subentry @code{getopt()}
Modern Unix systems provide a C function named @code{getopt()} for processing
command-line arguments. The programmer provides a string describing the
one-letter options. If an option requires an argument, it is followed in the
@@ -23339,6 +23377,7 @@ We have left it alone, as using @code{substr()} is more
portable.}
The discussion that follows walks through the code a bit at a time:
@cindex @code{getopt()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getopt()}
@example
@c file eg/lib/getopt.awk
# getopt.awk --- Do C library getopt(3) function in awk
@@ -23381,6 +23420,7 @@ a string of options (the @code{options} parameter). If
@code{options}
has a zero length, @code{getopt()} immediately returns @minus{}1:
@cindex @code{getopt()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getopt()}
@example
@c file eg/lib/getopt.awk
function getopt(argc, argv, options, thisopt, i)
@@ -23580,7 +23620,7 @@ use @code{getopt()} to process their arguments.
@cindex libraries of @command{awk} functions @subentry user database @subentry
reading
@cindex functions @subentry library @subentry user database, reading
address@hidden user address@hidden reading
address@hidden user database, reading
@cindex database @subentry users, reading
@cindex @code{PROCINFO} array
The @code{PROCINFO} array
@@ -23595,7 +23635,9 @@ user database. @xref{Group Functions}
for a similar suite that retrieves information from the group database.
@cindex @code{getpwent()} function (C library)
address@hidden C library functions @subentry @code{getpwent()}
@cindex @code{getpwent()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getpwent()}
@cindex users @subentry information about @subentry retrieving
@cindex login information
@cindex account information
@@ -23728,8 +23770,8 @@ shell, such as Bash.
A few lines representative of @command{pwcat}'s output are as follows:
@cindex Jacobs, Andrew
address@hidden Robbins, Arnold
address@hidden Robbins, Miriam
address@hidden Robbins @subentry Arnold
address@hidden Robbins @subentry Miriam
@example
$ @kbd{pwcat}
@print{} root:x:0:1:Operator:/:/bin/sh
@@ -23748,6 +23790,7 @@ information. There are several functions here,
corresponding to the C
functions of the same names:
@cindex @code{_pw_init()} user-defined function
address@hidden user-defined @subentry function @subentry @code{_pw_init()}
@example
@c file eg/lib/passwdawk.in
# passwd.awk --- access password file information
@@ -23840,12 +23883,14 @@ if necessary), @code{RS}, and @code{$0}.
The use of @address@hidden is explained shortly.
@cindex @code{getpwnam()} function (C library)
address@hidden C library functions @subentry @code{getpwnam()}
The @code{getpwnam()} function takes a username as a string argument. If that
user is in the database, it returns the appropriate line. Otherwise, it
relies on the array reference to a nonexistent
element to create the element with the null string as its value:
@cindex @code{getpwnam()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getpwnam()}
@example
@group
@c file eg/lib/passwdawk.in
@@ -23859,11 +23904,13 @@ function getpwnam(name)
@end example
@cindex @code{getpwuid()} function (C library)
address@hidden C library functions @subentry @code{getpwuid()}
Similarly, the @code{getpwuid()} function takes a user ID number
argument. If that user number is in the database, it returns the
appropriate line. Otherwise, it returns the null string:
@cindex @code{getpwuid()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getpwuid()}
@example
@c file eg/lib/passwdawk.in
function getpwuid(uid)
@@ -23875,11 +23922,13 @@ function getpwuid(uid)
@end example
@cindex @code{getpwent()} function (C library)
address@hidden C library functions @subentry @code{getpwent()}
The @code{getpwent()} function simply steps through the database, one entry at
a time. It uses @code{_pw_count} to track its current position in the
@code{_pw_bycount} array:
@cindex @code{getpwent()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getpwent()}
@example
@c file eg/lib/passwdawk.in
function getpwent()
@@ -23893,10 +23942,12 @@ function getpwent()
@end example
@cindex @code{endpwent()} function (C library)
address@hidden C library functions @subentry @code{endpwent()}
The @address@hidden()}} function resets @address@hidden to zero, so that
subsequent calls to @code{getpwent()} start over again:
@cindex @code{endpwent()} user-defined function
address@hidden user-defined @subentry function @subentry @code{endpwent()}
@example
@c file eg/lib/passwdawk.in
function endpwent()
@@ -23937,8 +23988,10 @@ uses these functions.
@cindex database @subentry group, reading
@cindex @code{PROCINFO} array @subentry group membership and
@cindex @code{getgrent()} function (C library)
address@hidden C library functions @subentry @code{getgrent()}
@cindex @code{getgrent()} user-defined function
address@hidden address@hidden information about
address@hidden user-defined @subentry function @subentry @code{getgrent()}
address@hidden groups, information about
@cindex account information
@cindex group file
@cindex files @subentry group
@@ -24079,6 +24132,7 @@ There are several, modeled after the C library
functions of the same names:
@cindex @code{getline} command @subentry @code{_gr_init()} user-defined
function
@cindex @code{_gr_init()} user-defined function
address@hidden user-defined @subentry function @subentry @code{_gr_init()}
@example
@c file eg/lib/groupawk.in
# group.awk --- functions for dealing with the group file
@@ -24192,6 +24246,7 @@ initializes @code{_gr_count} to zero
(it is used later), and makes @code{_gr_inited} nonzero.
@cindex @code{getgrnam()} function (C library)
address@hidden C library functions @subentry @code{getgrnam()}
The @code{getgrnam()} function takes a group name as its argument, and if that
group exists, it is returned.
Otherwise, it
@@ -24199,6 +24254,7 @@ relies on the array reference to a nonexistent
element to create the element with the null string as its value:
@cindex @code{getgrnam()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getgrnam()}
@example
@c file eg/lib/groupawk.in
function getgrnam(group)
@@ -24210,10 +24266,12 @@ function getgrnam(group)
@end example
@cindex @code{getgrgid()} function (C library)
address@hidden C library functions @subentry @code{getgrgid()}
The @code{getgrgid()} function is similar; it takes a numeric group ID and
looks up the information associated with that group ID:
@cindex @code{getgrgid()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getgrgid()}
@example
@c file eg/lib/groupawk.in
function getgrgid(gid)
@@ -24225,10 +24283,12 @@ function getgrgid(gid)
@end example
@cindex @code{getgruser()} function (C library)
address@hidden C library functions @subentry @code{getgruser()}
The @code{getgruser()} function does not have a C counterpart. It takes a
username and returns the list of groups that have the user as a member:
@cindex @code{getgruser()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getgruser()}
@example
@c file eg/lib/groupawk.in
function getgruser(user)
@@ -24240,10 +24300,12 @@ function getgruser(user)
@end example
@cindex @code{getgrent()} function (C library)
address@hidden C library functions @subentry @code{getgrent()}
The @code{getgrent()} function steps through the database one entry at a time.
It uses @code{_gr_count} to track its position in the list:
@cindex @code{getgrent()} user-defined function
address@hidden user-defined @subentry function @subentry @code{getgrent()}
@example
@c file eg/lib/groupawk.in
function getgrent()
@@ -24259,10 +24321,12 @@ function getgrent()
@end example
@cindex @code{endgrent()} function (C library)
address@hidden C library functions @subentry @code{endgrent()}
The @code{endgrent()} function resets @code{_gr_count} to zero so that
@code{getgrent()} can
start over again:
@cindex @code{endgrent()} user-defined function
address@hidden user-defined @subentry function @subentry @code{endgrent()}
@example
@c file eg/lib/groupawk.in
function endgrent()
@@ -24299,6 +24363,7 @@ You call it with the array and a string representing
the name
of the array:
@cindex @code{walk_array()} user-defined function
address@hidden user-defined @subentry function @subentry @code{walk_array()}
@example
@c file eg/lib/walkarray.awk
function walk_array(arr, name, i)
@@ -26112,7 +26177,7 @@ We hope you find them both interesting and enjoyable.
@cindex words @subentry duplicate, searching for
@cindex searching @subentry for words
address@hidden address@hidden searching
address@hidden documents, searching
A common error when writing large amounts of prose is to accidentally
duplicate words. Typically you will see this in text as something like ``the
the program does the address@hidden'' When the text is online, often
@@ -26180,7 +26245,7 @@ word, comparing it to the previous one:
@node Alarm Program
@subsection An Alarm Clock Program
@cindex insomnia, cure for
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Arnold
@quotation
@i{Nothing cures insomnia like a ringing alarm clock.}
@author Arnold Robbins
@@ -26223,6 +26288,7 @@ repetitions.
This program uses the @code{getlocaltime()} function from
@ref{Getlocaltime Function}.
address@hidden ASCII
All the work is done in the @code{BEGIN} rule. The first part is argument
checking and setting of defaults: the delay, the count, and the message to
print. If the user supplied a message without the ASCII BEL
@@ -26521,7 +26587,7 @@ for inspiration.
@subsection Printing Mailing Labels
@cindex printing @subentry mailing labels
address@hidden mailing address@hidden printing
address@hidden mailing labels, printing
Here is a ``real-world''@footnote{``Real world'' is defined as
``a program actually used to get something done.''}
program. This
@@ -28064,7 +28130,7 @@ things considerably. What problem does this engender
though?
@cindex search paths
@cindex search paths @subentry for source files
address@hidden source address@hidden search path for
address@hidden source files, search path for
@cindex files @subentry source, search path for
@cindex directories @subentry searching @subentry for source files
@item
@@ -28243,7 +28309,7 @@ disabled. If you want it, you must explicitly request
it.
@cindex programming conventions @subentry @code{--non-decimal-data} option
@cindex @option{--non-decimal-data} option @subentry @code{strtonum()}
function and
address@hidden @code{strtonum()} function (@command{gawk}),
@code{--non-decimal-data} option and
address@hidden @code{strtonum()} function (@command{gawk}) @subentry
@code{--non-decimal-data} option and
@quotation CAUTION
@emph{Use of this option is not recommended.}
It can break old programs very badly.
@@ -28534,6 +28600,7 @@ function should use the @code{isarray()} function
(@pxref{Type Functions})
to check for this, and choose a defined sorting order for subarrays.
address@hidden POSIX mode
All sorting based on @code{PROCINFO["sorted_in"]}
is disabled in POSIX mode,
because the @code{PROCINFO} array is not special in that case.
@@ -28554,8 +28621,10 @@ sorted array traversal is not the default.
@cindex arrays @subentry sorting @subentry @code{asorti()} function
(@command{gawk})
@cindexgawkfunc{asort}
@cindex @code{asort()} function (@command{gawk}) @subentry arrays, sorting
address@hidden @code{asort()} function (@command{gawk}) @subentry side effects
@cindexgawkfunc{asorti}
@cindex @code{asorti()} function (@command{gawk}) @subentry arrays, sorting
address@hidden @code{asorti()} function (@command{gawk}) @subentry side effects
@cindex sort function, arrays, sorting
In most @command{awk} implementations, sorting an array requires writing
a @code{sort()} function. This can be educational for exploring
@@ -28580,6 +28649,7 @@ All numeric values come before all string values,
which in turn come before all subarrays.
@cindex side effects @subentry @code{asort()} function
address@hidden side effects @subentry @code{asorti()} function
An important side effect of calling @code{asort()} is that
@emph{the array's original indices are irrevocably lost}.
As this isn't always desirable, @code{asort()} accepts a
@@ -28840,7 +28910,7 @@ These strings tell @command{gawk} to close the end of
the pipe
that sends data to the coprocess or the end that reads from it,
respectively.
address@hidden @command{sort} utility, coprocesses and
address@hidden @command{sort} utility @subentry coprocesses and
This is particularly necessary in order to use
the system @command{sort} utility as part of a coprocess;
@command{sort} must read @emph{all} of its input
@@ -28875,6 +28945,7 @@ indication. This causes @command{sort} to sort the
data and write the
sorted data back to the @command{gawk} program. Once all of the data
has been read, @command{gawk} terminates the coprocess and exits.
address@hidden ASCII
As a side note, the assignment @samp{LC_ALL=C} in the @command{sort}
command ensures traditional Unix (ASCII) sorting from @command{sort}.
This is not strictly necessary here, but it's good to know how to do this.
@@ -29048,6 +29119,7 @@ respectively. TCP should be used for most applications.
@item local-port
@cindex @code{getaddrinfo()} function (C library)
address@hidden C library functions @subentry @code{getaddrinfo()}
The local TCP or UDP port number to use. Use a port number of @samp{0}
when you want the system to pick a port. This is what you should do
when writing a TCP or UDP client.
@@ -29248,7 +29320,7 @@ Multiple @code{BEGIN} and @code{END} rules retain their
separate identities, as do
multiple @code{BEGINFILE} and @code{ENDFILE} rules.
address@hidden patterns @subentry counts @subentry in a profile
address@hidden patterns @subentry counts, in a profile
@item
Pattern--action rules have two counts.
The first count, to the left of the rule, shows how many times
@@ -29347,7 +29419,7 @@ which is correct, but possibly unexpected.
(If a program uses both @samp{print $0} and plain
@samp{print}, that distinction is retained.)
address@hidden profiling @command{awk} programs, dynamically
address@hidden profiling @command{awk} programs @subentry dynamically
@cindex @command{gawk} @subentry dynamic profiling
@cindex @command{gawk} @subentry profiling programs
@cindex dynamic profiling
@@ -29363,10 +29435,10 @@ $ @kbd{gawk --profile -f myprog &}
[1] 13992
@end example
address@hidden @command{kill} address@hidden dynamic profiling
address@hidden @command{kill} command, dynamic profiling
@cindex @code{USR1} signal, for dynamic profiling
@cindex @code{SIGUSR1} signal, for dynamic profiling
address@hidden signals @subentry @code{USR1}/@code{SIGUSR1} @subentry for
profiling
address@hidden signals @subentry @code{USR1}/@code{SIGUSR1}, for profiling
@noindent
The shell prints a job number and process ID number; in this case, 13992.
Use the @command{kill} command to send the @code{USR1} signal
@@ -29399,7 +29471,7 @@ profile file.
@cindex @code{HUP} signal, for dynamic profiling
@cindex @code{SIGHUP} signal, for dynamic profiling
address@hidden signals @subentry @code{HUP}/@code{SIGHUP} @subentry for
profiling
address@hidden signals @subentry @code{HUP}/@code{SIGHUP}, for profiling
If you use the @code{HUP} signal instead of the @code{USR1} signal,
@command{gawk} produces the profile and the function call trace and then exits.
@@ -29428,8 +29500,8 @@ Once upon a time, the @option{--pretty-print} option
would also run
your program. This is is no longer the case.
@end quotation
address@hidden profiling, pretty-printing, difference with
address@hidden pretty-printing, profiling, difference with
address@hidden profiling, pretty printing, difference with
address@hidden pretty printing @subentry profiling, difference with
There is a significant difference between the output created when
profiling, and that created when pretty-printing. Pretty-printed output
preserves the original comments that were in the program, although their
@@ -29541,7 +29613,7 @@ a requirement.
@section Internationalization and Localization
@cindex internationalization
address@hidden localization @address@hidden localization}
address@hidden localization @seeentry{internationalization, localization}
@cindex internationalization @subentry localization
@dfn{Internationalization} means writing (or modifying) a program once,
in such a way that it can use multiple languages without requiring
@@ -29589,6 +29661,7 @@ A table with strings of option names is not (e.g.,
@command{gawk}'s
language).
@cindex @code{textdomain()} function (C library)
address@hidden C library functions @subentry @code{textdomain()}
@item
The programmer indicates the application's text domain
(@command{"guide"}) to the @command{gettext} library,
@@ -29632,6 +29705,7 @@ When @command{guide} is built and installed, the binary
translation files
are installed in a standard place.
@cindex @code{bindtextdomain()} function (C library)
address@hidden C library functions @subentry @code{bindtextdomain()}
@item
For testing and development, it is possible to tell @command{gettext}
to use @file{.gmo} files in a different directory than the standard
@@ -29654,6 +29728,7 @@ and forth.
@end enumerate
@cindex @code{gettext()} function (C library)
address@hidden C library functions @subentry @code{gettext()}
In C (or C++), the string marking and dynamic translation lookup
are accomplished by wrapping each string in a call to @code{gettext()}:
@@ -29751,6 +29826,7 @@ All of the above. (Not too useful in the context of
@command{gettext}.)
@quotation NOTE
@cindex @env{LANGUAGE} environment variable
address@hidden environment variables @subentry @env{LANGUAGE}
As described in @ref{Locales}, environment variables with the same
name as the locale categories (@env{LC_CTYPE}, @env{LC_ALL}, etc.)
influence @command{gawk}'s behavior (and that of other utilities).
@@ -29917,7 +29993,7 @@ printf(message, ncustomers)
@end example
address@hidden @code{LC_MESSAGES} locale category, @code{bindtextdomain()}
function (@command{gawk})
address@hidden @code{LC_MESSAGES} locale category @subentry
@code{bindtextdomain()} function (@command{gawk})
@item
During development, you might want to put the @file{.gmo}
file in a private directory for testing. This is done
@@ -29971,7 +30047,7 @@ is covered.
@cindex strings @subentry extracting
@cindex @option{--gen-pot} option
@cindex command line @subentry options @subentry string extraction
address@hidden string extraction (internationalization)
address@hidden string @subentry extraction (internationalization)
@cindex marked string extraction (internationalization)
@cindex extraction, of marked strings (internationalization)
@@ -30925,7 +31001,7 @@ controlling breakpoints are:
@cindex debugger commands @subentry @code{break}
@cindex @code{break} debugger command
@cindex @code{b} debugger command (alias for @code{break})
address@hidden set breakpoint
address@hidden set @subentry breakpoint
@cindex breakpoint @subentry setting
@item @code{break} address@hidden@code{:address@hidden | @var{function}]
address@hidden"@var{expression}"}]
@itemx @code{b} address@hidden@code{:address@hidden | @var{function}]
address@hidden"@var{expression}"}]
@@ -31282,7 +31358,7 @@ You can also set special @command{awk} variables, such
as @code{FS},
@cindex debugger commands @subentry @code{watch}
@cindex @code{watch} debugger command
@cindex @code{w} debugger command (alias for @code{watch})
address@hidden set watchpoint
address@hidden set @subentry watchpoint
@item @code{watch} @var{var} | @address@hidden
address@hidden"@var{expression}"}]
@itemx @code{w} @var{var} | @address@hidden address@hidden"@var{expression}"}]
Add variable @var{var} (or field @address@hidden) to the watch list.
@@ -31388,11 +31464,13 @@ The value for @var{what} should be one of the
following:
@c nested table
@table @code
@item args
address@hidden show function arguments, in debugger
address@hidden show in debugger @subentry function arguments
address@hidden function arguments, show in debugger
List arguments of the selected frame.
@item break
address@hidden show breakpoints
address@hidden show in debugger @subentry breakpoints
address@hidden breakpoints, show in debugger
List all currently set breakpoints.
@item display
@@ -31405,15 +31483,19 @@ Give a description of the selected stack frame.
@item functions
@cindex list function definitions, in debugger
address@hidden function definitions, list in debugger
List all function definitions including source @value{FN}s and
line numbers.
@item locals
address@hidden show local variables, in debugger
address@hidden show in debugger @subentry local variables
address@hidden local variables, show in debugger
List local variables of the selected frame.
@item source
address@hidden show name of current source file, in debugger
address@hidden show in debugger @subentry name of current source file
address@hidden current source file, show in debugger
address@hidden source file, show in debugger
Print the name of the current source file. Each time the program stops, the
current source file is the file containing the current instruction.
When the debugger first starts, the current source file is the first file
@@ -31422,15 +31504,18 @@ included via the @option{-f} option. The
be used at any time to change the current source.
@item sources
address@hidden show all source files, in debugger
address@hidden show in debugger @subentry all source files
address@hidden all source files, show in debugger
List all program sources.
@item variables
@cindex list all global variables, in debugger
address@hidden global variables, show in debugger
List all global variables.
@item watch
address@hidden show watchpoints
address@hidden show in debugger @subentry watchpoints
address@hidden watchpoints, show in debugger
List all items in the watch list.
@end table
@end table
@@ -31899,7 +31984,7 @@ please report them (@xref{Bugs}).
@section Standard @command{awk}'s Single Namespace
@cindex namespace @subentry definition of
address@hidden namespace @subentry standard @command{awk} @subentry global
address@hidden namespace @subentry standard @command{awk}, global
In standard @command{awk}, there is a single, global, @dfn{namespace}.
This means that @emph{all} function names and global variable names must
be unique. For example, two different @command{awk} source files cannot
@@ -31977,6 +32062,7 @@ It also keeps your code looking natural.
@cindex namespaces @subentry changing
@cindex @code{@@} (at-sign) @subentry @code{@@namespace} directive
@cindex at-sign (@code{@@}) @subentry @code{@@namespace} directive
address@hidden @code{@@namespace} directive @sortas{namespace directive}
In order to set the current namespace, use an @code{@@namespace} directive
at the top level of your program:
@@ -32018,19 +32104,20 @@ directive is seen. When @command{gawk} finishes
processing the included
file, the saved namespace is restored and processing continues where it
left off in the original file.
address@hidden @code{@@} (at-sign) @subentry @code{@@namespace} directive
@subentry no effect on @code{BEGIN}, @code{BEGINFILE}, @code{END}, and
@code{ENDFILE}
address@hidden at-sign (@code{@@}) @subentry @code{@@namespace} directive
@subentry no effect on @code{BEGIN}, @code{BEGINFILE}, @code{END}, and
@code{ENDFILE}
address@hidden @code{BEGIN} pattern @subentry execution order not affected by
@code{@@namespace}
address@hidden @code{BEGINFILE} pattern @subentry execution order not affected
by @code{@@namespace}
address@hidden @code{END} pattern @subentry execution order not affected by
@code{@@namespace}
address@hidden @code{ENDFILE} pattern @subentry execution order not affected by
@code{@@namespace}
address@hidden @code{@@} (at-sign) @subentry @code{@@namespace} directive
@subentry @code{BEGIN}, @code{BEGINFILE}, @code{END}, @code{ENDFILE} and
address@hidden at-sign (@code{@@}) @subentry @code{@@namespace} directive
@subentry @code{BEGIN}, @code{BEGINFILE}, @code{END}, @code{ENDFILE} and
address@hidden @code{BEGIN} pattern @subentry @code{@@namespace} directive and
address@hidden @code{BEGINFILE} pattern @subentry @code{@@namespace} directive
and
address@hidden @code{END} pattern @subentry @code{@@namespace} directive and
address@hidden @code{ENDFILE} pattern @subentry @code{@@namespace} directive and
address@hidden @code{@@namespace} directive @sortas{namespace directive}
The use of @code{@@namespace} has no influence upon the order of execution
of @code{BEGIN}, @code{BEGINFILE}, @code{END}, and @code{ENDFILE} rules.
@node Naming Rules
@section Namespace and Component Naming Rules
address@hidden naming rules, namespaces and component names
address@hidden naming rules, namespace and component names
@cindex namespace names, naming rules
@cindex component names @subentry naming rules
A number of rules apply to the namespace and component names, as follows.
@@ -32257,8 +32344,8 @@ $ @kbd{gawk -f ns_passwd.awk -f testpasswd.awk}
This @value{SECTION} looks briefly at how the namespace facility interacts
with other important @command{gawk} features.
address@hidden namespaces @subentry interaction with profiler
address@hidden namespaces @subentry interaction with pretty printer
address@hidden namespaces @subentry interaction with @subentry profiler
address@hidden namespaces @subentry interaction with @subentry pretty printer
@cindex profiler, interaction with namespaces
@cindex pretty printer, interaction with namespaces
The profiler and pretty-printer (@pxref{Profiling}) have been enhanced
@@ -32268,14 +32355,14 @@ namespace together, and has @code{@@namespace}
directives in front
of rules as necessary. This allows component names to be
simple identifiers, instead of using qualified identifiers everywhere.
address@hidden namespaces @subentry interaction with debugger
address@hidden namespaces @subentry interaction with @subentry debugger
@cindex debugger @subentry interaction with namespaces
Interaction with the debugger (@pxref{Debugging}) has not had to change
(at least as of this writing). Some of the internal byte codes changed
in order to accommodate namespaces, and the debugger's @code{dump} command
was adjusted to match.
address@hidden namespaces @subentry interaction with extension API
address@hidden namespaces @subentry interaction with @subentry extension API
@cindex extension API @subentry interaction with namespaces
The extension API (@pxref{Dynamic Extensions}) has always allowed for
placing functions into a different namespace, although this was not
@@ -33129,7 +33216,7 @@ output when you change the rounding mode to be sure.
@node Arbitrary Precision Integers
@section Arbitrary-Precision Integer Arithmetic with @command{gawk}
@cindex integers @subentry arbitrary precision
address@hidden arbitrary precision integers
address@hidden arbitrary precision @subentry integers
When given the @option{-M} option,
@command{gawk} performs all integer arithmetic using GMP arbitrary-precision
@@ -33361,9 +33448,8 @@ word sizes. See
@node Checking for MPFR
@section How To Check If MPFR Is Available
address@hidden MPFR @subentry checking availability of
@cindex checking for MPFR
address@hidden MPFR @subentry checking for
address@hidden MPFR, checking for
Occasionally, you might like to be able to check if @command{gawk}
was invoked with the @option{-M} option, enabling arbitrary-precision
arithmetic. You can do so with the following function, contributed
@@ -33515,6 +33601,7 @@ $ @kbd{echo 0xDeadBeef | gawk '@{ print $1 + 0 @}'}
Thus, @samp{+nan} and @samp{+NaN} are the same.
@end itemize
address@hidden POSIX mode
Besides handling input, @command{gawk} also needs to print ``correct'' values
on
output when a value is either NaN or infinity. Starting with @value{PVERSION}
4.2.2, for such values @command{gawk} prints one of the four strings
@@ -34010,7 +34097,7 @@ the macros as if they were functions.
@node General Data Types
@subsection General-Purpose Data Types
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Arnold
@cindex Ramey, Chet
@quotation
@i{I have a true love/hate relationship with unions.}
@@ -34413,7 +34500,7 @@ to be a @samp{char *} value pointing to data previously
obtained from
@node Registration Functions
@subsection Registration Functions
address@hidden register extension
address@hidden register loadable extension
@cindex extensions @subentry loadable @subentry registration
This @value{SECTION} describes the API functions for
@@ -35093,7 +35180,7 @@ Register the two-way processor pointed to by
@code{two_way_processor} with
@node Printing Messages
@subsection Printing Messages
address@hidden printing messages from extensions
address@hidden printing @subentry messages from extensions
@cindex messages from extensions
You can print different kinds of warning messages from your
@@ -39392,6 +39479,7 @@ a global symbol indicating that they are GPL-compatible
(@pxref{Plugin License}).
@item
address@hidden POSIX mode
In POSIX mode, string comparisons use @code{strcoll()} / @code{wcscoll()}
(@pxref{POSIX String Comparison}).
@@ -39678,6 +39766,8 @@ This @value{SECTION} describes the confusing history of
ranges within
regular expressions and their interactions with locales, and how this
affected different versions of @command{gawk}.
address@hidden ASCII
address@hidden EBCDIC
The original Unix tools that worked with regular expressions defined
character ranges (such as @samp{[a-z]}) to match any character between
the first character in the range and the last character in the range,
@@ -39735,6 +39825,7 @@ This result is due to the locale setting (and thus you
may not see
it on your system).
@cindex Unicode
address@hidden ASCII
Similar considerations apply to other ranges. For example, @samp{["-/]}
is perfectly valid in ASCII, but is not valid in many Unicode locales,
such as @code{en_US.UTF-8}.
@@ -39964,7 +40055,7 @@ of IBM in Japan, contributed support for multibyte
characters.
Michael Benzinger contributed the initial code for @code{switch} statements.
@item
address@hidden McPhee, Patrick
address@hidden McPhee, Patrick T.J.@:
Patrick T.J.@: McPhee contributed the code for dynamic loading in Windows32
environments.
(This is no longer supported.)
@@ -40046,7 +40137,7 @@ distribution.
Juan Manuel Guerrero took over maintenance of the DJGPP port.
@item
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Arnold
Arnold Robbins
has been working on @command{gawk} since 1988, at first
helping David Trueman, and as the primary maintainer since around 1994.
@@ -40074,6 +40165,8 @@ They can be disabled with either the
@option{--traditional} or @option{--posix}
options.
@item
address@hidden ASCII
address@hidden EBCDIC
The interaction of POSIX locales and regexp matching in @command{gawk} has
been confusing over
the years. Today, @command{gawk} implements Rational Range Interpretation,
where
ranges of the form @samp{[a-z]} match @emph{only} the characters numerically
between
@@ -40091,7 +40184,10 @@ the appropriate credit where credit is due.
@appendix Installing @command{gawk}
@c last two commas are part of see also
address@hidden operating systems @seealso{GNU/address@hidden PC operating
address@hidden Unix}
address@hidden operating systems
address@hidden operating systems @seealso{GNU/Linux}
address@hidden operating systems @seealso{PC operating systems}
address@hidden operating systems @seealso{Unix}
@cindex @command{gawk} @subentry installing
@cindex installing @command{gawk}
This appendix provides instructions for installing @command{gawk} on the
@@ -40261,7 +40357,7 @@ A description of behaviors in the POSIX standard for
@command{awk} that
are left undefined, or where @command{gawk} may not comply fully, as well
as a list of things that the POSIX standard should describe but does not.
address@hidden artificial address@hidden @command{gawk} and
address@hidden artificial intelligence, @command{gawk} and
@item doc/awkforai.txt
Pointers to the original draft of
a short article describing why @command{gawk} is a good language for
@@ -40542,7 +40638,7 @@ Add the argument to the end of the @env{AWKLIBPATH}
environment variable.
@node Additional Configuration Options
@appendixsubsec Additional Configuration Options
@cindex @command{gawk} @subentry configuring @subentry options
address@hidden configuration address@hidden @command{gawk}
address@hidden configuration options, @command{gawk}
There are several additional options you may use on the @command{configure}
command line when compiling @command{gawk} from scratch, including:
@@ -40671,7 +40767,7 @@ various non-Unix systems.
@node PC Installation
@appendixsubsec Installation on MS-Windows
address@hidden PC operating address@hidden @command{gawk} on, installing
address@hidden PC operating systems, @command{gawk} on @subentry installing
@cindex operating systems @subentry PC, @command{gawk} on @subentry installing
This @value{SECTION} covers installation and usage of @command{gawk}
on Intel architecture machines running any version of MS-Windows.
@@ -40722,8 +40818,8 @@ type @samp{make mingw32}.
@node PC Using
@appendixsubsubsec Using @command{gawk} on PC Operating Systems
address@hidden operating systems, PC, @command{gawk} on
address@hidden PC operating systems @subentry @command{gawk} on
address@hidden operating systems @subentry PC, @command{gawk} on
address@hidden PC operating systems, @command{gawk} on
Information in this section applies to the MinGW and
DJGPP ports of @command{gawk}. @xref{Cygwin} for information
@@ -40740,6 +40836,7 @@ The DJGPP environment does not support @samp{|&}.
@cindex @code{;} (semicolon) @subentry @env{AWKPATH} variable and
@cindex semicolon (@code{;}) @subentry @env{AWKPATH} variable and
@cindex @env{AWKPATH} environment variable
address@hidden environment variables @subentry @env{AWKPATH}
The MS-Windows version of @command{gawk} searches for
program files as described in @ref{AWKPATH Variable}. However,
semicolons (rather than colons) separate elements in the @env{AWKPATH}
@@ -41409,7 +41506,7 @@ The people maintaining the various @command{gawk} ports
are:
@cindex Malmberg, John
@cindex Pitts, Dave
@cindex G., Daniel Richard
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Arnold
@cindex Zaretskii, Eli
@cindex Guerrero, Juan Manuel
@multitable {MS-Windows with MinGW}
{123456789012345678901234567890123456789001234567890}
@@ -41556,7 +41653,7 @@ since approximately 2001.
@cindex Beebe, Nelson H.F.@:
@cindex @command{pawk} (profiling version of Brian Kernighan's @command{awk})
address@hidden source code @subentry @command{pawk}
address@hidden source code @subentry @command{pawk} (profiling version of Brian
Kernighan's @command{awk})
@item @command{pawk}
Nelson H.F.@: Beebe at the University of Utah has modified
BWK @command{awk} to provide timing and profiling information.
@@ -41628,7 +41725,7 @@ This is an embeddable @command{awk} interpreter derived
from
@command{mawk}. For more information, see
@uref{http://repo.hu/projects/libmawk/}.
address@hidden source code, embeddable @command{awk} interpreter
address@hidden source code @subentry embeddable @command{awk} interpreter
@cindex Neacsu, Mircea
@item Mircea Neacsu's Embeddable @command{awk}
Mircea Neacsu has created an embeddable @command{awk}
@@ -42343,7 +42440,7 @@ Larry
@end ignore
@cindex Perl
@cindex Wall, Larry
address@hidden Robbins, Arnold
address@hidden Robbins @subentry Arnold
@quotation
@i{AWK is a language similar to PERL, only considerably more elegant.}
@author Arnold Robbins
@@ -42793,7 +42890,7 @@ and even more often, as ``I/O'' for short.
(You will also see ``input'' and ``output'' used as verbs.)
@cindex data-driven languages
address@hidden address@hidden data-driven
address@hidden languages, data-driven
@command{awk} manages the reading of data for you, as well as the
breaking it up into records and fields. Your program's job is to
tell @command{awk} what to do with the data. You do this by describing
@@ -43326,6 +43423,7 @@ The epoch on Unix and POSIX systems is 1970-01-01
00:00:00 UTC.
See also ``GMT'' and ``UTC.''
@item Escape Sequences
address@hidden ASCII
A special sequence of characters used for describing nonprinting
characters, such as @samp{\n} for newline or @samp{\033} for the ASCII
ESC (Escape) character. (@xref{Escape Sequences}.)
@@ -45235,3 +45333,5 @@ Add a section explaining recursion from ground zero.
Probably
easiest to do it with factorial as the example. Explain that
recursion needs a stopping condition. Thanks to
Bill Duncan <address@hidden> for the suggestion.
+
+Add an entry for all env vars @cindex environment variables @subentry
@env{FOO}.
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index dd756de..d3078ba 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -4101,7 +4101,7 @@ be used to cancel the effect of an earlier @option{-s}
option
@itemx @address@hidden@var{file}]
@cindex @option{-p} option
@cindex @option{--profile} option
address@hidden @command{awk} profiling, enabling
address@hidden @command{awk} @subentry profiling, enabling
Enable profiling of @command{awk} programs
(@pxref{Profiling}).
Implies @option{--no-optimize}.
@@ -4267,6 +4267,7 @@ the command line that follow the program text are entered
into the
command line looking for options.
@cindex @env{POSIXLY_CORRECT} environment variable
address@hidden environment variables @subentry @env{POSIXLY_CORRECT}
@cindex lint checking @subentry @env{POSIXLY_CORRECT} environment variable
@cindex POSIX mode
If the environment variable @env{POSIXLY_CORRECT} exists,
@@ -4433,6 +4434,7 @@ behaves.
@node AWKPATH Variable
@subsection The @env{AWKPATH} Environment Variable
@cindex @env{AWKPATH} environment variable
address@hidden environment variables @subentry @env{AWKPATH}
@cindex directories @subentry searching @subentry for source files
@cindex search paths @subentry for source files
@cindex differences in @command{awk} and @command{gawk} @subentry
@env{AWKPATH} environment variable
@@ -4519,6 +4521,7 @@ found, and @command{gawk} no longer needs to use
@env{AWKPATH}.
@node AWKLIBPATH Variable
@subsection The @env{AWKLIBPATH} Environment Variable
@cindex @env{AWKLIBPATH} environment variable
address@hidden environment variables @subentry @env{AWKLIBPATH}
@cindex directories @subentry searching @subentry for loadable extensions
@cindex search paths @subentry for loadable extensions
@cindex differences in @command{awk} and @command{gawk} @subentry
@code{AWKLIBPATH} environment variable
@@ -5093,7 +5096,7 @@ $ @kbd{awk '/li/ @{ print $2 @}' mail-list}
@cindex operators @subentry string-matching
@c @cindex operators, @code{~}
@cindex string-matching operators
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -5199,6 +5202,7 @@ all the escape sequences used in @command{awk} and
what they represent. Unless noted otherwise, all these escape
sequences apply to both string constants and regexp constants:
address@hidden ASCII
@table @code
@item \\
A literal backslash, @samp{\}.
@@ -5463,7 +5467,7 @@ The condition in the following example is not true:
if ("line1\nLINE 2" ~ /1$/) @dots{}
@end example
address@hidden @code{.} (period) @subentry regexp operator
address@hidden @code{.} (period), regexp operator
@cindex period (@code{.}), regexp operator
@item @code{.} (period)
This matches any single character,
@@ -5770,6 +5774,7 @@ depends on various factors out of our control.
@c Thanks to
@c Date: Tue, 01 Jul 2014 07:39:51 +0200
@c From: Hermann Peifer <address@hidden>
address@hidden ASCII
Some utilities that match regular expressions provide a nonstandard
@samp{[:ascii:]} character class; @command{awk} does not. However, you
can simulate such a construct using @samp{[\x00-\x7F]}. This matches
@@ -5874,7 +5879,7 @@ and also @pxref{Field Separators}).
@cindex regular expressions @subentry computed
@cindex regular expressions @subentry dynamic
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -6184,7 +6189,7 @@ This works in any POSIX-compliant @command{awk}.
@cindex @command{gawk} @subentry regular expressions @subentry case sensitivity
@cindex case sensitivity @subentry @command{gawk}
@cindex differences in @command{awk} and @command{gawk} @subentry regular
expressions
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -10635,6 +10640,7 @@ double quotation marks. For example:
@noindent
@cindex differences in @command{awk} and @command{gawk} @subentry strings
@cindex strings @subentry length limitations
address@hidden ASCII
represents the string whose contents are @samp{parrot}. Strings in
@command{gawk} can be of any length, and they can contain any of the possible
eight-bit ASCII characters, including ASCII @sc{nul} (character code zero).
@@ -10808,7 +10814,7 @@ $ @kbd{gawk 'BEGIN @{ printf "0x11 is <%s>\n", 0x11 @}'}
@subsubsection Regular Expression Constants
@cindex regexp constants
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -12405,7 +12411,7 @@ operators}, which are a superset of those in C.
@cindex equals sign (@code{=}) @subentry @code{==} operator
@cindex @code{!} (exclamation point) @subentry @code{!=} operator
@cindex exclamation point (@code{!}) @subentry @code{!=} operator
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -12519,7 +12525,7 @@ x ~ /foo/
has the value one if @code{x} contains @samp{foo}, such as
@code{"Oh, what a fool am I!"}.
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -13063,7 +13069,7 @@ parentheses. Such combinations (e.g., @samp{print foo
> a ? b : c})
result in syntax errors.
The correct way to write this statement is @samp{print foo > (a ? b : c)}.
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -13343,7 +13349,7 @@ whose first field is precisely @samp{li}:
@cindex @code{/} (forward slash) @subentry patterns and
@cindex forward slash (@code{/}) @subentry patterns and
address@hidden @code{~} (tilde) @subentry @code{~} operator
address@hidden @code{~} (tilde), @code{~} operator
@cindex tilde (@code{~}), @code{~} operator
@cindex @code{!} (exclamation point) @subentry @code{!~} operator
@cindex exclamation point (@code{!}) @subentry @code{!~} operator
@@ -16053,7 +16059,7 @@ that have not been assigned any value as well as
elements that have been
deleted (@pxref{Delete}).
@cindex non-existent array elements
address@hidden arrays @subentry elements that don't exist
address@hidden arrays @subentry elements @subentry that don't exist
@quotation NOTE
A reference to an element that does not exist @emph{automatically} creates
that array element, with the null string as its value. (In some cases,
@@ -25293,6 +25299,7 @@ repetitions.
This program uses the @code{getlocaltime()} function from
@ref{Getlocaltime Function}.
address@hidden ASCII
All the work is done in the @code{BEGIN} rule. The first part is argument
checking and setting of defaults: the delay, the count, and the message to
print. If the user supplied a message without the ASCII BEL
@@ -27949,6 +27956,7 @@ indication. This causes @command{sort} to sort the
data and write the
sorted data back to the @command{gawk} program. Once all of the data
has been read, @command{gawk} terminates the coprocess and exits.
address@hidden ASCII
As a side note, the assignment @samp{LC_ALL=C} in the @command{sort}
command ensures traditional Unix (ASCII) sorting from @command{sort}.
This is not strictly necessary here, but it's good to know how to do this.
@@ -28829,6 +28837,7 @@ All of the above. (Not too useful in the context of
@command{gettext}.)
@quotation NOTE
@cindex @env{LANGUAGE} environment variable
address@hidden environment variables @subentry @env{LANGUAGE}
As described in @ref{Locales}, environment variables with the same
name as the locale categories (@env{LC_CTYPE}, @env{LC_ALL}, etc.)
influence @command{gawk}'s behavior (and that of other utilities).
@@ -31064,6 +31073,7 @@ It also keeps your code looking natural.
@cindex namespaces @subentry changing
@cindex @code{@@} (at-sign) @subentry @code{@@namespace} directive
@cindex at-sign (@code{@@}) @subentry @code{@@namespace} directive
address@hidden @code{@@namespace} directive @sortas{namespace directive}
In order to set the current namespace, use an @code{@@namespace} directive
at the top level of your program:
@@ -31105,12 +31115,13 @@ directive is seen. When @command{gawk} finishes
processing the included
file, the saved namespace is restored and processing continues where it
left off in the original file.
address@hidden @code{@@} (at-sign) @subentry @code{@@namespace} directive
@subentry no effect on @code{BEGIN}, @code{BEGINFILE}, @code{END}, and
@code{ENDFILE}
address@hidden at-sign (@code{@@}) @subentry @code{@@namespace} directive
@subentry no effect on @code{BEGIN}, @code{BEGINFILE}, @code{END}, and
@code{ENDFILE}
address@hidden @code{BEGIN} pattern @subentry execution order not affected by
@code{@@namespace}
address@hidden @code{BEGINFILE} pattern @subentry execution order not affected
by @code{@@namespace}
address@hidden @code{END} pattern @subentry execution order not affected by
@code{@@namespace}
address@hidden @code{ENDFILE} pattern @subentry execution order not affected by
@code{@@namespace}
address@hidden @code{@@} (at-sign) @subentry @code{@@namespace} directive
@subentry @code{BEGIN}, @code{BEGINFILE}, @code{END}, @code{ENDFILE} and
address@hidden at-sign (@code{@@}) @subentry @code{@@namespace} directive
@subentry @code{BEGIN}, @code{BEGINFILE}, @code{END}, @code{ENDFILE} and
address@hidden @code{BEGIN} pattern @subentry @code{@@namespace} directive and
address@hidden @code{BEGINFILE} pattern @subentry @code{@@namespace} directive
and
address@hidden @code{END} pattern @subentry @code{@@namespace} directive and
address@hidden @code{ENDFILE} pattern @subentry @code{@@namespace} directive and
address@hidden @code{@@namespace} directive @sortas{namespace directive}
The use of @code{@@namespace} has no influence upon the order of execution
of @code{BEGIN}, @code{BEGINFILE}, @code{END}, and @code{ENDFILE} rules.
@@ -32177,7 +32188,7 @@ output when you change the rounding mode to be sure.
@node Arbitrary Precision Integers
@section Arbitrary-Precision Integer Arithmetic with @command{gawk}
@cindex integers @subentry arbitrary precision
address@hidden arbitrary precision integers
address@hidden arbitrary precision @subentry integers
When given the @option{-M} option,
@command{gawk} performs all integer arithmetic using GMP arbitrary-precision
@@ -38727,6 +38738,8 @@ This @value{SECTION} describes the confusing history of
ranges within
regular expressions and their interactions with locales, and how this
affected different versions of @command{gawk}.
address@hidden ASCII
address@hidden EBCDIC
The original Unix tools that worked with regular expressions defined
character ranges (such as @samp{[a-z]}) to match any character between
the first character in the range and the last character in the range,
@@ -38784,6 +38797,7 @@ This result is due to the locale setting (and thus you
may not see
it on your system).
@cindex Unicode
address@hidden ASCII
Similar considerations apply to other ranges. For example, @samp{["-/]}
is perfectly valid in ASCII, but is not valid in many Unicode locales,
such as @code{en_US.UTF-8}.
@@ -39123,6 +39137,8 @@ They can be disabled with either the
@option{--traditional} or @option{--posix}
options.
@item
address@hidden ASCII
address@hidden EBCDIC
The interaction of POSIX locales and regexp matching in @command{gawk} has
been confusing over
the years. Today, @command{gawk} implements Rational Range Interpretation,
where
ranges of the form @samp{[a-z]} match @emph{only} the characters numerically
between
@@ -39792,6 +39808,7 @@ The DJGPP environment does not support @samp{|&}.
@cindex @code{;} (semicolon) @subentry @env{AWKPATH} variable and
@cindex semicolon (@code{;}) @subentry @env{AWKPATH} variable and
@cindex @env{AWKPATH} environment variable
address@hidden environment variables @subentry @env{AWKPATH}
The MS-Windows version of @command{gawk} searches for
program files as described in @ref{AWKPATH Variable}. However,
semicolons (rather than colons) separate elements in the @env{AWKPATH}
@@ -40680,7 +40697,7 @@ This is an embeddable @command{awk} interpreter derived
from
@command{mawk}. For more information, see
@uref{http://repo.hu/projects/libmawk/}.
address@hidden source code, embeddable @command{awk} interpreter
address@hidden source code @subentry embeddable @command{awk} interpreter
@cindex Neacsu, Mircea
@item Mircea Neacsu's Embeddable @command{awk}
Mircea Neacsu has created an embeddable @command{awk}
@@ -42378,6 +42395,7 @@ The epoch on Unix and POSIX systems is 1970-01-01
00:00:00 UTC.
See also ``GMT'' and ``UTC.''
@item Escape Sequences
address@hidden ASCII
A special sequence of characters used for describing nonprinting
characters, such as @samp{\n} for newline or @samp{\033} for the ASCII
ESC (Escape) character. (@xref{Escape Sequences}.)
@@ -44287,3 +44305,5 @@ Add a section explaining recursion from ground zero.
Probably
easiest to do it with factorial as the example. Explain that
recursion needs a stopping condition. Thanks to
Bill Duncan <address@hidden> for the suggestion.
+
+Add an entry for all env vars @cindex environment variables @subentry
@env{FOO}.
-----------------------------------------------------------------------
Summary of changes:
ChangeLog | 5 +
doc/gawk.texi | 392 +++++++++++++++++++++++++++++++++++---------------------
doc/gawktexi.in | 58 ++++++---
msg.c | 2 +-
4 files changed, 291 insertions(+), 166 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, feature/better-index, updated. gawk-4.1.0-3748-g5484684,
Arnold Robbins <=