Generate Pod::Functions from perlfunc.pod

This avoids it getting out of synchronisation.

2 files changed, 110 insertions, 255 deletions

diff --git a/ext/Pod-Functions/Functions_pm.PL b/ext/Pod-Functions/Functions_pm.PL
index f8329d23cd..8d1f17d2ce 100644
--- a/ext/Pod-Functions/Functions_pm.PL
+++ b/ext/Pod-Functions/Functions_pm.PL
@@ -1,5 +1,90 @@
 #!perl -w
 use strict;
+use Pod::Simple::SimpleTree;
+
+my (%Kinds, %Flavor, @Types);
+my %Omit;
+
+my $p = Pod::Simple::SimpleTree->new;
+$p->accept_targets('Pod::Functions');
+my $tree = $p->parse_file(shift)->root;
+
+foreach my $TL_node (@$tree[2 .. $#$tree]) {
+    next unless $TL_node->[0] eq 'over-text';
+    my $i = 2;
+    while ($i <= $#$TL_node) {
+        if ($TL_node->[$i][0] ne 'item-text') {
+            ++$i;
+            next;
+        }
+
+        my $item_text = $TL_node->[$i][2];
+        die "Confused by $item_text at line $TL_node->[$i][1]{start_line}"
+            if ref $item_text;
+        $item_text =~ s/\s+\z//s;
+
+        if ($TL_node->[$i+1][0] ne 'for'
+           || $TL_node->[$i+1][1]{target} ne 'Pod::Functions') {
+            ++$i;
+            next;
+        }
+        my $data = $TL_node->[$i+1][2];
+        die "Confused by $data at line $TL_node->[$i+1][1]{start_line}"
+            unless ref $data eq 'ARRAY';
+        my $text = $data->[2];
+        die "Confused by $text at line $TL_node->[$i+1][1]{start_line}"
+            if ref $text;
+
+        $i += 2;
+
+        if ($text =~ s/^=//) {
+            # We are in "Perl Functions by Category"
+            die "Expected a paragraph after =item at $TL_node->[$i-2][1]{start_line}"
+                unless $TL_node->[$i][0] eq 'Para';
+            my $para = $TL_node->[$i];
+            # $text is the "type" of the built-in
+            # Anything starting ! is not for inclusion in Pod::Functions
+
+            foreach my $func (@$para[2 .. $#$para]) {
+                next unless ref $func eq 'ARRAY';
+                die "Expected only C<> blocks in paragraph after item at $TL_node->[$i-2][1]{start_line}"
+                    unless $func->[0] eq 'C' && !ref $func->[2];
+                # Everything is plain text (ie $func->[2] is everything)
+                # except for C<-I<X>>. So untangle up to one level of nested <>
+                my $funcname = join '', map {
+                    ref $_ ? $_->[2] : $_
+                } @$func[2..$#$func];
+                $funcname =~ s!(q.?)//!$1/STRING/!;
+                push @{$Kinds{$text}}, $funcname;
+            }
+            if ($text =~ /^!/) {
+                ++$Omit{$_} foreach @{$Kinds{$text}};
+            } else {
+                push @Types, [$text, $item_text];
+            }
+        } else {
+            $item_text =~ s/ .*//;
+            $Flavor{$item_text} = $text;
+            ++$Omit{$item_text} if $text =~ /^!/;
+        }
+    }
+}
+
+# Take the lists of functions for each type group, and invert them to get the
+# type group (or groups) for each function:
+my %Type;
+while (my ($type, $funcs) = each %Kinds) {
+    push @{$Type{$_}}, $type foreach @$funcs;
+}
+
+# We sort __SUB__ after sub, but before substr, but __PACKAGE__ after package,
+# and __END__ after END.
+sub sort_funcs {
+    map { $_->[0] }
+        sort { uc $a->[1] cmp uc $b->[1] || $b->[1] cmp $a->[1] || $a->[0] cmp $b->[0] }
+            map  { my $f = tr/_//dr; [ $_, $f ] }
+                @_;
+}
 
 # blead will run this with miniperl, hence we can't use autodie
 my $real = 'Functions.pm';
@@ -16,11 +101,7 @@ foreach ($real, $temp) {
 }
 
 open my $fh, '>', $temp or die "Can't open '$temp' for writing: $!";
-print $fh <DATA> or die "Can't write to '$temp': $!";
-close $fh or die "Can't close '$temp': $!";
-rename $temp, $real or die "Can't rename '$temp' to '$real': $!";
-
-__END__
+print $fh <<'EOT';
 package Pod::Functions;
 use strict;
 
@@ -87,27 +168,16 @@ our @EXPORT = qw(%Kinds %Type %Flavor %Type_Description @Type_Order);
 our(%Kinds, %Type, %Flavor, %Type_Description, @Type_Order);
 
 foreach (
-    [String	=> 'Functions for SCALARs or strings'],
-    [Regexp	=> 'Regular expressions and pattern matching'],
-    [Math	=> 'Numeric functions'],
-    [ARRAY	=> 'Functions for real @ARRAYs'],
-    [LIST	=> 'Functions for list data'],
-    [HASH	=> 'Functions for real %HASHes'],
-    ['I/O'	=> 'Input and output functions'],
-    [Binary	=> 'Functions for fixed-length data or records'],
-    [File	=> 'Functions for filehandles, files, or directories'],
-    [Flow	=> 'Keywords related to the control flow of your Perl program'],
-    [Switch	=> 'Keywords related to the switch feature'],
-    [Namespace	=> 'Keywords related to scoping'],
-    [Misc	=> 'Miscellaneous functions'],
-    [Process	=> 'Functions for processes and process groups'],
-    [Modules	=> 'Keywords related to Perl modules'],
-    [Objects	=> 'Keywords related to classes and object-orientation'],
-    [Socket	=> 'Low-level socket functions'],
-    [SysV	=> 'System V interprocess communication functions'],
-    [User	=> 'Fetching user and group info'],
-    [Network	=> 'Fetching network info'],
-    [Time	=> 'Time-related functions'],
+EOT
+
+foreach (@Types) {
+    my ($type, $desc) = @$_;
+    $type = "'$type'" if $type =~ /[^A-Za-z]/;
+    $desc =~ s!([\\'])!\\$1!g;
+    printf $fh "    [%-9s  => '%s'],\n", $type, $desc;
+}
+
+print $fh <<'EOT';
 	) {
     push @Type_Order, $_->[0];
     $Type_Description{$_->[0]} = $_->[1];
@@ -115,7 +185,7 @@ foreach (
 
 while (<DATA>) {
     chomp;
-    s/#.*//;
+    s/^#.*//;
     next unless $_;
     my($name, $type, $text) = split " ", $_, 3;
     $Type{$name} = $type;
@@ -149,230 +219,15 @@ format =
 1;
 
 __DATA__
--X	File	a file test (-r, -x, etc)
-abs	Math	absolute value function
-accept	Socket	accept an incoming socket connect
-alarm	Process	schedule a SIGALRM 
-atan2	Math	arctangent of Y/X in the range -PI to PI
-bind	Socket	binds an address to a socket
-binmode	I/O	prepare binary files for I/O
-bless	Objects	create an object 
-break	Switch	Break out of a C<given()> block
-caller	Flow,Namespace	get context of the current subroutine call
-chdir	File	change your current working directory
-chmod	File	changes the permissions on a list of files
-chomp	String 	remove a trailing record separator from a string
-chop	String 	remove the last character from a string
-chown	File	change the ownership on a list of files
-chr	String 	get character this number represents
-chroot	File	make directory new root for path lookups
-close	I/O	close file (or pipe or socket) handle
-closedir	I/O	close directory handle
-connect	Socket	connect to a remote socket
-continue	Flow,Switch	optional trailing block in a while or foreach 
-cos	Math	cosine function
-crypt	String	one-way passwd-style encryption
-dbmclose	Objects,I/O	breaks binding on a tied dbm file
-dbmopen	Objects,I/O	create binding on a tied dbm file
-default	Switch	XXX RT #108848
-defined	Misc	test whether a value, variable, or function is defined
-delete	HASH	deletes a value from a hash
-die	I/O,Flow	raise an exception or bail out
-do	Flow,Modules	turn a BLOCK into a TERM
-dump	Misc,Flow	create an immediate core dump
-each	ARRAY,HASH	retrieve the next key/value pair from a hash
-endgrent	User	be done using group file
-endhostent	User	be done using hosts file
-endnetent	User	be done using networks file
-endprotoent	Network	be done using protocols file
-endpwent	User	be done using passwd file
-endservent	Network	be done using services file
-eof	I/O	test a filehandle for its end
-eval	Flow,Misc	catch exceptions or compile and run code
-evalbytes	Flow,Misc	similar to string eval, but intend to parse a bytestream
-exec	Process	abandon this program to run another
-exists	HASH	test whether a hash key is present
-exit	Flow	terminate this program
-exp	Math	raise I<e> to a power
-fc	String	return casefolded version of a string
-fcntl	File	file control system call
-__FILE__	Flow	the name of the current source file
-fileno	I/O	return file descriptor from filehandle
-flock	I/O	lock an entire file with an advisory lock
-fork	Process	create a new process just like this one
-format	I/O	declare a picture format with use by the write() function
-formline	Misc	internal function used for formats
-getc	I/O	get the next character from the filehandle
-getgrent	User	get next group record 
-getgrgid	User	get group record given group user ID
-getgrnam	User	get group record given group name
-gethostbyaddr	Network	get host record given its address
-gethostbyname	Network	get host record given name
-gethostent	Network	get next hosts record 
-getlogin	User	return who logged in at this tty
-getnetbyaddr	Network	get network record given its address
-getnetbyname	Network	get networks record given name
-getnetent	Network	get next networks record 
-getpeername	Socket	find the other end of a socket connection
-getpgrp	Process	get process group
-getppid	Process	get parent process ID
-getpriority	Process	get current nice value
-getprotobyname	Network	get protocol record given name
-getprotobynumber	Network	get protocol record numeric protocol
-getprotoent	Network	get next protocols record
-getpwent	User	get next passwd record
-getpwnam	User	get passwd record given user login name
-getpwuid	User	get passwd record given user ID
-getservbyname	Network	get services record given its name
-getservbyport	Network	get services record given numeric port
-getservent	Network	get next services record 
-getsockname	Socket	retrieve the sockaddr for a given socket
-getsockopt	Socket	get socket options on a given socket
-given	Switch	XXX RT #108848
-glob	File		expand filenames using wildcards
-gmtime	Time	convert UNIX time into record or string using Greenwich time
-goto	Flow	create spaghetti code
-grep	LIST	locate elements in a list test true against a given criterion
-hex	Math,String	convert a string to a hexadecimal number
-import	Modules,Namespace	patch a module's namespace into your own
-index	String	find a substring within a string
-int	Math	get the integer portion of a number
-ioctl	File	system-dependent device control system call
-join	LIST	join a list into a string using a separator
-keys	ARRAY,HASH	retrieve list of indices from a hash
-kill	Process	send a signal to a process or process group
-last	Flow	exit a block prematurely
-lc	String	return lower-case version of a string
-lcfirst	String	return a string with just the next letter in lower case
-length	String	return the number of bytes in a string
-__LINE__	Flow	the current source line number
-link	File	create a hard link in the filesystem
-listen	Socket	register your socket as a server 
-local	Misc,Namespace	create a temporary value for a global variable (dynamic scoping)
-localtime	Time	convert UNIX time into record or string using local time
-lock	Misc	get a thread lock on a variable, subroutine, or method
-log	Math	retrieve the natural logarithm for a number
-lstat	File	stat a symbolic link
-m//	Regexp	match a string with a regular expression pattern
-map	LIST	apply a change to a list to get back a new list with the changes
-mkdir	File	create a directory
-msgctl	SysV	SysV IPC message control operations
-msgget	SysV	get SysV IPC message queue
-msgrcv	SysV	receive a SysV IPC message from a message queue
-msgsnd	SysV	send a SysV IPC message to a message queue
-my	Misc,Namespace	declare and assign a local variable (lexical scoping)
-next	Flow	iterate a block prematurely
-no	Modules	unimport some module symbols or semantics at compile time
-package	Modules,Objects,Namespace	declare a separate global namespace
-__PACKAGE__	Flow	the current package
-prototype	Flow,Misc	get the prototype (if any) of a subroutine
-oct	String,Math	convert a string to an octal number
-open	File	open a file, pipe, or descriptor
-opendir	File	open a directory
-ord	String	find a character's numeric representation
-our	Misc,Namespace	declare and assign a package variable (lexical scoping)
-pack	Binary,String	convert a list into a binary representation
-pipe	Process	open a pair of connected filehandles
-pop	ARRAY	remove the last element from an array and return it
-pos	Regexp	find or set the offset for the last/next m//g search
-print	I/O	output a list to a filehandle
-printf	I/O  	output a formatted list to a filehandle
-push	ARRAY	append one or more elements to an array
-q/STRING/	String	singly quote a string
-qq/STRING/	String	doubly quote a string
-quotemeta	Regexp	quote regular expression magic characters
-qw/STRING/	LIST	quote a list of words
-qx/STRING/	Process	backquote quote a string
-qr/STRING/	Regexp	Compile pattern 
-rand	Math	retrieve the next pseudorandom number 
-read	I/O,Binary	fixed-length buffered input from a filehandle
-readdir	I/O	get a directory from a directory handle
-readline	I/O	fetch a record from a file
-readlink	File	determine where a symbolic link is pointing
-readpipe	Process	execute a system command and collect standard output
-recv	Socket	receive a message over a Socket
-redo	Flow	start this loop iteration over again
-ref	Objects	find out the type of thing being referenced
-rename	File	change a filename
-require	Modules	load in external functions from a library at runtime
-reset	Misc	clear all variables of a given name
-return	Flow	get out of a function early
-reverse	String,LIST	flip a string or a list
-rewinddir	I/O	reset directory handle
-rindex	String	right-to-left substring search
-rmdir	File	remove a directory
-s///	Regexp	replace a pattern with a string
-say	I/O	output a list to a filehandle, appending a newline
-scalar	Misc	force a scalar context
-seek	I/O	reposition file pointer for random-access I/O
-seekdir	I/O	reposition directory pointer 
-select	I/O	reset default output or do I/O multiplexing
-semctl	SysV	SysV semaphore control operations
-semget	SysV	get set of SysV semaphores
-semop	SysV	SysV semaphore operations
-send	Socket	send a message over a socket
-setgrent	User	prepare group file for use
-sethostent	Network	prepare hosts file for use
-setnetent	Network	prepare networks file for use
-setpgrp	Process	set the process group of a process
-setpriority	Process	set a process's nice value
-setprotoent	Network	prepare protocols file for use
-setpwent	User	prepare passwd file for use
-setservent	Network	prepare services file for use
-setsockopt	Socket	set some socket options
-shift	ARRAY	remove the first element of an array, and return it
-shmctl	SysV	SysV shared memory operations
-shmget	SysV	get SysV shared memory segment identifier
-shmread	SysV	read SysV shared memory 
-shmwrite	SysV	write SysV shared memory 
-shutdown	Socket	close down just half of a socket connection
-sin	Math	return the sine of a number
-sleep	Process	block for some number of seconds
-socket	Socket	create a socket
-socketpair	Socket	create a pair of sockets
-sort	LIST	sort a list of values 
-splice	ARRAY	add or remove elements anywhere in an array
-split	Regexp	split up a string using a regexp delimiter
-sprintf	String	formatted print into a string
-sqrt	Math	square root function
-srand	Math	seed the random number generator
-stat	File	get a file's status information
-state	Misc,Namespace	declare and assign a persistent lexical variable
-study	Regexp	optimize input data for repeated searches
-sub	Flow	declare a subroutine, possibly anonymously
-__SUB__	Flow	the current subroutine, or C<undef> if not in a subroutine
-substr	String	get or alter a portion of a string
-symlink	File	create a symbolic link to a file
-syscall	I/O,Binary	execute an arbitrary system call
-sysopen	File	open a file, pipe, or descriptor
-sysread	I/O,Binary	fixed-length unbuffered input from a filehandle
-sysseek	I/O,Binary	position I/O pointer on handle used with sysread and syswrite
-system	Process	run a separate program 
-syswrite	I/O,Binary	fixed-length unbuffered output to a filehandle
-tell	I/O	get current seekpointer on a filehandle
-telldir	I/O	get current seekpointer on a directory handle
-tie	Objects	bind a variable to an object class 
-tied	Objects	get a reference to the object underlying a tied variable
-time	Time	return number of seconds since 1970
-times	Process,Time	return elapsed time for self and child processes
-tr///	String	transliterate a string
-truncate	I/O	shorten a file
-uc	String	return upper-case version of a string
-ucfirst	String	return a string with just the next letter in upper case
-umask	File	set file creation mode mask
-undef	Misc	remove a variable or function definition
-unlink	File	remove one link to a file
-unpack	Binary,LIST	convert binary structure into normal perl variables
-unshift	ARRAY	prepend more elements to the beginning of a list
-untie	Objects	break a tie binding to a variable
-use	Objects,Modules,Namespace	load in a module at compile time and import its namespace
-utime	File	set a file's last access and modify times
-values	ARRAY,HASH	return a list of the values in a hash
-vec	Binary	test or set particular bits in a string
-wait	Process	wait for any child process to die
-waitpid	Process	wait for  a particular child process to die
-wantarray	Misc,Flow	get void vs scalar vs list context of current subroutine call
-warn	I/O	print debugging info
-when	Switch	XXX RT #108848
-write	I/O	print a picture record
-y///	String	transliterate a string
+EOT
+
+foreach my $func (sort_funcs(keys %Flavor)) {
+    my $desc = $Flavor{$func};
+    die "No types listed for $func" unless $Type{$func};
+    next if $Omit{$func};
+    my $types = join ',', @{$Type{$func}};
+    print $fh "$func\t$types\t$desc\n";
+}
+
+close $fh or die "Can't close '$temp': $!";
+rename $temp, $real or die "Can't rename '$temp' to '$real': $!";
diff --git a/ext/Pod-Functions/t/Functions.t b/ext/Pod-Functions/t/Functions.t
index e4e70e19df..099e4ac832 100644
--- a/ext/Pod-Functions/t/Functions.t
+++ b/ext/Pod-Functions/t/Functions.t
@@ -110,7 +110,7 @@ Keywords related to the control flow of your Perl program:
      last, next, prototype, redo, return, sub, wantarray
 
 Keywords related to the switch feature:
-     break, continue, default, given, when
+     break, continue
 
 Keywords related to scoping:
      caller, import, local, my, our, package, state, use