Merge branch 'master' into array-iface

1 files changed, 130 insertions, 44 deletions

diff --git a/doc/gawk.1 b/doc/gawk.1
index f01ffbfe..31fcef1f 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -14,7 +14,7 @@
 .		if \w'\(rq' .ds rq "\(rq
 .	\}
 .\}
-.TH GAWK 1 "Nov 10 2011" "Free Software Foundation" "Utility Commands"
+.TH GAWK 1 "Oct 02 2012" "Free Software Foundation" "Utility Commands"
 .SH NAME
 gawk \- pattern scanning and processing language
 .SH SYNOPSIS
@@ -323,6 +323,19 @@ the standard output.
 these options cause an immediate, successful exit.)
 .TP
 .PD 0
+.BI "\-i " include-file
+.TP
+.PD
+.BI \-\^\-include " include-file"
+Load an awk source library.
+This searches for the library using the
+.B AWKPATH
+environment variable.  If the initial search fails, another attempt will
+be made after appending the ".awk" suffix.  The file will be loaded only
+once (i.e. duplicates are eliminated), and the code does not constitute
+the main program source.
+.TP
+.PD 0
 .BI "\-l " lib
 .TP
 .PD
@@ -330,12 +343,11 @@ these options cause an immediate, successful exit.)
 Load a shared library
 .IR lib .
 This searches for the library using the
-.B AWKPATH
-environment variable. The suffix 
-.I .so
-in the library name is optional, and
-the library initialization routine is expected to be named
-.BR dlload() .
+.B AWKLIBPATH
+environment variable.  If the initial search fails, another attempt will
+be made after appending the default shared library suffix for the platform.
+The library initialization routine is expected to be named
+.BR dl_load() .
 .TP
 .PD 0
 .BR "\-L " [ \fIvalue\fR ]
@@ -574,6 +586,9 @@ and optional function definitions.
 .RS
 .PP
 \fB@include "\fIfilename\fB"
+.br
+\fB@load "\fIfilename\fB"
+.br
 \fIpattern\fB	{ \fIaction statements\fB }\fR
 .br
 \fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR
@@ -605,12 +620,21 @@ In addition, lines beginning with
 may be used to include other source files into your program,
 making library use even easier.
 .PP
+Lines beginning with
+.B @load
+may be used to load shared libraries into your program.  This is equivalent
+to using the
+.B \-l 
+option.
+.PP
 The environment variable
 .B AWKPATH
 specifies a search path to use when finding source files named with
 the
 .B \-f
-option.  If this variable does not exist, the default path is
+and
+.B \-i
+options.  If this variable does not exist, the default path is
 \fB".:/usr/local/share/awk"\fR.
 (The actual directory may vary, depending upon how
 .I gawk
@@ -965,6 +989,17 @@ The input field separator, a space by default.  See
 .BR Fields ,
 above.
 .TP
+.B FUNCTAB
+An array whose indices are the names of all the user-defined
+or extension functions in the program.
+.BR NOTE :
+The array values cannot currently be used.
+Also, you may not use the
+.B delete
+statment with the
+.B FUNCTAB
+array.
+.TP
 .B IGNORECASE
 Controls the case-sensitivity of all regular expression
 and string operations.  If
@@ -1084,6 +1119,35 @@ or \fB"FIELDWIDTHS"\fP if field splitting with
 .B FIELDWIDTHS
 is in effect.
 .TP
+\fBPROCINFO["identifiers"]\fP
+A subarray, indexed by the names of all identifiers used in the
+text of the AWK program.  For each identifier, the value of the element is one of the following:
+.RS
+.TP
+\fB"array"\fR
+The identifier is an array.
+.TP
+\fB"extension"\fR
+The identifier is an extension function loaded via
+.BR @load .
+.TP
+\fB"scalar"\fR
+The identifier is a scalar.
+.TP
+\fB"untyped"\fR
+The identifier is untyped (could be used as a scalar or array,
+.I gawk
+doesn't know yet).
+.TP
+\fB"user"\fR
+The identifier is a user-defined function.
+.RE
+The values indicate what
+.I gawk
+knows about the identifiers after it has finished parsing the program; they are
+.I not
+updated while the program runs.
+.TP
 \fBPROCINFO["gid"]\fP
 the value of the
 .IR getgid (2)
@@ -1212,6 +1276,30 @@ The length of the string matched by
 The character used to separate multiple subscripts in array
 elements, by default \fB"\e034"\fR.
 .TP
+.B SYMTAB
+An array whose indices are the names of all currently defined
+global variables and arrays in the program.  The array may be used
+for indirect access to read or write the value of a variable:
+.PP
+.RS
+.ft B
+foo = 5
+SYMTAB["foo"] = 4
+print foo    # prints 4
+.ft R
+.RE
+.PP
+The
+.B isarray()
+function may be used to test if an element in
+.B SYMTAB
+is an array.
+You may not use the
+.B delete
+statment with the
+.B SYMTAB
+array.
+.TP
 .B TEXTDOMAIN
 The text domain of the \*(AK program; used to find the localized
 translations for the program's strings.
@@ -2953,11 +3041,9 @@ integers, doing the operation, and then converting the
 result back to floating point.
 The functions are:
 .TP "\w'\fBrshift(\fIval\fB, \fIcount\fB)\fR'u+2n"
-\fBand(\fIv1\fB, \fIv2\fB)\fR
-Return the bitwise AND of the values provided by
-.I v1
-and
-.IR v2 .
+\fBand(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
+Return the bitwise AND of the values provided in the argument list.
+There must be at least two.
 .TP
 \fBcompl(\fIval\fB)\fR
 Return the bitwise complement of
@@ -2970,11 +3056,9 @@ shifted left by
 .I count
 bits.
 .TP
-\fBor(\fIv1\fB, \fIv2\fB)\fR
-Return the bitwise OR of the values provided by
-.I v1
-and
-.IR v2 .
+\fBor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
+Return the bitwise OR of the values provided in the argument list.
+There must be at least two.
 .TP
 \fBrshift(\fIval\fB, \fIcount\fB)\fR
 Return the value of
@@ -2983,11 +3067,9 @@ shifted right by
 .I count
 bits.
 .TP
-\fBxor(\fIv1\fB, \fIv2\fB)\fR
-Return the bitwise XOR of the values provided by
-.I v1
-and
-.IR v2 .
+\fBxor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
+Return the bitwise XOR of the values provided in the argument list.
+There must be at least two.
 .PP
 .SS Type Function
 The following function is for use with multidimensional arrays.
@@ -3163,24 +3245,11 @@ may be used in place of
 .SH DYNAMICALLY LOADING NEW FUNCTIONS
 You can dynamically add new built-in functions to the running
 .I gawk
-interpreter.
+interpreter with the
+.B @load
+statement.
 The full details are beyond the scope of this manual page;
-see \*(EP for the details.
-.PP
-.TP 8
-\fBextension(\fIobject\fB, \fIfunction\fB)\fR
-Dynamically link the shared object file named by
-.IR object ,
-and invoke
-.I function
-in that object, to perform initialization.
-These should both be provided as strings.
-Return the value returned by
-.IR function .
-.PP
-Using this feature at the C level is not pretty, but
-it is unlikely to go away. Additional mechanisms may
-be added at some point.
+see \*(EP.
 .SH SIGNALS
 The
 .I gawk
@@ -3634,8 +3703,23 @@ environment variable can be used to provide a list of directories that
 .I gawk
 searches when looking for files named via the
 .B \-f
-and
+,
 .B \-\^\-file
+,
+.B \-i
+and
+.B \-\^\-include
+options.  If the initial search fails, the path is searched again after
+appending ".awk" to the filename.
+.PP
+The
+.B AWKLIBPATH
+environment variable can be used to provide a list of directories that
+.I gawk
+searches when looking for files named via the
+.B \-l
+and
+.B \-\^\-load
 options.
 .PP
 The
@@ -3694,7 +3778,7 @@ status is 2.  On non-POSIX systems, this value may be mapped to
 .SH VERSION INFORMATION
 This man page documents
 .IR gawk ,
-version 4.0.
+version 4.1.
 .SH AUTHORS
 The original version of \*(UX
 .I awk
@@ -3772,6 +3856,7 @@ While the
 developers occasionally read this newsgroup, posting bug reports there
 is an unreliable way to report bugs.  Instead, please use the electronic mail
 addresses given above.
+Really.
 .PP
 If you're using a GNU/Linux or BSD-based system,
 you may wish to submit a bug report to the vendor of your distribution.
@@ -3791,6 +3876,7 @@ are surprisingly difficult to diagnose in the completely general case,
 and the effort to do so really is not worth it.
 .SH SEE ALSO
 .IR egrep (1),
+.IR sed (1),
 .IR getpid (2),
 .IR getppid (2),
 .IR getpgrp (2),
@@ -3806,7 +3892,7 @@ Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger,
 Addison-Wesley, 1988.  ISBN 0-201-07981-X.
 .PP
 \*(EP,
-Edition 4.0, shipped with the
+Edition 4.1, shipped with the
 .I gawk
 source.
 The current version of this document is available online at
@@ -3853,7 +3939,7 @@ We thank him.
 .SH COPYING PERMISSIONS
 Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996,
 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009,
-2010, 2011
+2010, 2011, 2012
 Free Software Foundation, Inc.
 .PP
 Permission is granted to make and distribute verbatim copies of