Document isarray etc.

8 files changed, 78 insertions, 14 deletions

diff --git a/ChangeLog b/ChangeLog
index ba1b127e..c8442631 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Tue Feb  1 10:20:02 2011  Arnold D. Robbins  <arnold@skeeve.com>
+
+	* eval.c (r_interpret): Change magic string for array sorting.
+
 Sun Jan 30 21:49:53 2011  John Haque  <j.eh@mchsi.com>
 
 	Add `isarray' built-in function.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index f562a54e..0b3ee48c 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+Tue Feb  1 10:21:22 2011  Arnold D. Robbins  <arnold@skeeve.com>
+
+	* gawk.texi, awkcard.in, gawk.1: Document isarray function,
+	magic string in PROCINFO for array sorting. Needs a little
+	more work in gawk.texi.
+
 Mon Jan 10 21:52:21 2011  Arnold D. Robbins  <arnold@skeeve.com>
 
 	* lflashlight.small.xpic, rflashlight.small.xpic: Original
diff --git a/doc/awkcard.in b/doc/awkcard.in
index 15a98281..898fea0c 100644
--- a/doc/awkcard.in
+++ b/doc/awkcard.in
@@ -1,7 +1,7 @@
 .\" AWK Reference Card --- Arnold Robbins, arnold@skeeve.com
 .\"
 .\" Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-.\" 2003, 2004, 2005, 2007, 2009, 2010 Free Software Foundation, Inc.
+.\" 2003, 2004, 2005, 2007, 2009, 2010, 2011 Free Software Foundation, Inc.
 .\" 
 .\" Permission is granted to make and distribute verbatim copies of
 .\" this reference card provided the copyright notice and this permission
@@ -80,6 +80,7 @@ Signals (\*(PK)
	4
 Special Filenames
	12
 String Functions
	16
 Time Functions (\*(GK)
	17
+Type Functions (\*(GK)
	18
 User-defined Functions
	15
 Variables
	5\*(CX
 .in -.2i
@@ -100,7 +101,7 @@ Brian Kernighan and Michael Brennan who reviewed it.
 .SL
 .nf
 \*(FRCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
-2005, 2007, 2009, 2010 Free Software Foundation, Inc.
+2005, 2007, 2009, 2010, 2011 Free Software Foundation, Inc.
 .nf
 .BT
 
@@ -1847,6 +1848,17 @@ It returns the value returned by
 .EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0"
 .BT
 
+.\" --- Type Functions
+.ES
+.fi
+.in +.2i
+.ti -.2i
+\*(CD\*(FCisarray(\*(FIx\*(FC)\*(FR
+.br
+Return true if \*(FIx\fP is an array, false otherwise.\*(CB
+.in -.2i
+.EB "\s+2\f(HBTYPE FUNCTIONS (\*(GK\f(HB)\*(FR\s0"
+.sp .5
 .\" --- Builtin Internationalization Functions
 .ES
 .fi
@@ -1886,8 +1898,8 @@ Return the plural form used for \*(FInumber\*(FR of the translation of
 \*(FIstring1\*(FR and \*(FIstring2\*(FR in text domain
 \*(FIdom\*(FR for locale category \*(FIcat\*(FR.
 The default value for \*(FIdom\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR.
-\*(FC"LC_MESSAGES"\*(FR
-is the default value for \*(FIcat\*(FR.
+The default for \*(FC"LC_MESSAGES"\*(FR
+is \*(FIcat\*(FR.
 .sp .5
 If you supply a value for \*(FIcat\*(FR, it must be a string equal to
 one of the known locale categories.
@@ -1895,7 +1907,7 @@ You must also supply a text domain.  Use \*(FCTEXTDOMAIN\*(FR
 to use the current domain.\*(CB
 .in -.2i
 .EB "\s+2\f(HBINTERNATIONALIZATION (\*(GK\f(HB)\*(FR\s0"
-
+.sp .5
 .\" --- FTP/HTTP Information
 .ES
 .nf
@@ -1906,7 +1918,7 @@ File: \*(FC/gnu/gawk/gawk-4.0.0.tar.gz\fP
 GNU \*(AK (\*(GK). There may be a later version.
 .in -.2i
 .nf
-.sp .5
+.sp .4
 \*(FChttp://www.cs.princeton.edu/~bwk/btl.mirror/
 awk.tar.gz\fP
 .in +.2i
@@ -1915,7 +1927,7 @@ awk.tar.gz\fP
 GCC (the GNU Compiler Collection) works well.
 .in -.2i
 .nf
-.sp .5
+.sp .4
 ... Host: \*(FCftp.whidbey.net\*(FR
 ... File: \*(FC/pub/brennan/mawk1.3.3.tar.gz\fP
 ... \*(FChttp://www.skeeve.com/gawk/mawk1.3.3.tar.gz\fP
@@ -1927,13 +1939,12 @@ Michael Brennan's \*(MK. Thomas Dickey now
 maintains it.\*(CX
 .in -.2i
 .EB "\s+2\f(HBFTP/HTTP INFORMATION\*(FR\s0"
-
-
+.sp .5
 .\" --- Copying Permissions
 .ES
 .fi
 \*(CDCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
-2007, 2009, 2010 Free Software Foundation, Inc.
+2007, 2009, 2010, 2011 Free Software Foundation, Inc.
 .sp .5   
 Permission is granted to make and distribute verbatim copies of this
 reference card provided the copyright notice and this permission notice
diff --git a/doc/gawk.1 b/doc/gawk.1
index 241e2c12..66ea4f15 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -14,7 +14,7 @@
 .		if \w'\(rq' .ds rq "\(rq
 .	\}
 .\}
-.TH GAWK 1 "Oct 21 2010" "Free Software Foundation" "Utility Commands"
+.TH GAWK 1 "Jan 31 2011" "Free Software Foundation" "Utility Commands"
 .SH NAME
 gawk \- pattern scanning and processing language
 .SH SYNOPSIS
@@ -1080,6 +1080,17 @@ the value of the
 .IR getuid (2)
 system call.
 .TP
+\fBPROCINFO["sorted_in"]\fP
+If this element exists in
+.BR PROCINFO ,
+.IR "no matter what its value" ,
+then
+.I gawk
+will cause array
+.B for
+loops
+to traverse the array indices in sorted order.
+.TP
 \fBPROCINFO["version"]\fP
 the version of
 .IR gawk .
@@ -2874,6 +2885,13 @@ Return the bitwise XOR of the values provided by
 and
 .IR v2 .
 .PP
+.SS Type Function
+The following function is for use with multidimensional arrays.
+.TP
+\fBisarray(\fIx\fB)\fR
+Return true if
+.I x
+is an array, false otherwise.
 .SS Internationalization Functions
 The following functions may be used from within your AWK program for
 translating strings at run-time.
@@ -3715,7 +3733,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
+2010, 2011
 Free Software Foundation, Inc.
 .PP
 Permission is granted to make and distribute verbatim copies of
diff --git a/doc/gawk.texi b/doc/gawk.texi
index e5f263b1..08fc7faf 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -527,6 +527,7 @@ particular records in a file and perform operations upon them.
 * I/O Functions::                  Functions for files and shell commands.
 * Time Functions::                 Functions for dealing with timestamps.
 * Bitwise Functions::              Functions for bitwise operations.
+* Type Functions::                 Functions for type information.
 * I18N Functions::                 Functions for string translation.
 * User-defined::                   Describes User-defined functions in detail.
 * Definition Syntax::              How to write definitions and what they
@@ -12710,6 +12711,12 @@ The parent process ID of the current process.
 @item PROCINFO["uid"]
 The value of the @code{getuid()} system call.
 
+@item PROCINFO["sorted_in"]
+If this element exists in @code{PROCINFO},
+@emph{no matter what its value},
+then @command{gawk} will cause @samp{for(i in arr) @dots{}} loops
+to traverse the array indices in sorted order.
+
 @item PROCINFO["strftime"]
 The default time format string for @code{strftime()}.
 Assigning a new value to this element changes the default.
@@ -14031,6 +14038,7 @@ but are summarized here for your convenience.
 * I/O Functions::               Functions for files and shell commands.
 * Time Functions::              Functions for dealing with timestamps.
 * Bitwise Functions::           Functions for bitwise operations.
+* Type Functions::              Functions for type information.
 * I18N Functions::              Functions for string translation.
 @end menu
 
@@ -16182,6 +16190,19 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions.
 @c ENDOFRANGE xor
 @c ENDOFRANGE opbit
 
+@node Type Functions
+@subsection Getting Type Information
+
+@command{gawk} provides a single function that lets you distinguish
+an array from a scalar variable.  This is necessary for writing code
+that traverses every element of a multidimensional array.
+
+@table @code
+@cindex @code{isarray()} function (@command{gawk})
+@item isarray(@var{x})
+Return a true value if @var{x} is an array. Otherwise return false.
+@end table
+
 @node I18N Functions
 @subsection String-Translation Functions
 @cindex @command{gawk}, string-translation functions
diff --git a/eval.c b/eval.c
index 59574633..ba2a4229 100644
--- a/eval.c
+++ b/eval.c
@@ -2256,7 +2256,7 @@ post:
 			static NODE *sorted_str = NULL;
 
 			if (sorted_str == NULL)
-				sorted_str = make_string("sorted_for_loop", 15);
+				sorted_str = make_string("sorted_in", 9);
 
 			/* get the array */
 			array = POP_ARRAY();
diff --git a/test/ChangeLog b/test/ChangeLog
index fb96b5ce..7bccdec8 100644
--- a/test/ChangeLog
+++ b/test/ChangeLog
@@ -1,3 +1,7 @@
+Tue Feb  1 10:20:47 2011  Arnold D. Robbins  <arnold@skeeve.com>
+
+	* sortfor.awk: Change magic string to match code.
+
 Thu Jan 27 22:56:19 2011  Arnold D. Robbins  <arnold@skeeve.com>
 
 	* Makefile.am (sortfor): New test.
diff --git a/test/sortfor.awk b/test/sortfor.awk
index 2b601c80..f61200da 100644
--- a/test/sortfor.awk
+++ b/test/sortfor.awk
@@ -1,5 +1,5 @@
 BEGIN {
-	PROCINFO["sorted_for_loop"] = 1
+	PROCINFO["sorted_in"] = 1
 }
 { a[$0]++ }
 END {