In perl.git, the branch smoke-me/Pod-Functions has been updated <http://perl5.git.perl.org/perl.git/commitdiff/29fff2df4342af588c81d5cccdde848ff7dd14af?hp=979b65a9795db7b091a432c9c8364952112b6bb1>
- Log ----------------------------------------------------------------- commit 29fff2df4342af588c81d5cccdde848ff7dd14af Author: Nicholas Clark <[email protected]> Date: Mon Jan 30 12:27:40 2012 +0100 In the generated Pod::Functions, store all function data with tab separation. Previously the data was stored with a comma separated list inside a tab separated list. M ext/Pod-Functions/Functions_pm.PL commit fb6ef2ae804aed4fb5fc6e864150dfccb3b51c4f Author: Nicholas Clark <[email protected]> Date: Mon Jan 30 12:15:36 2012 +0100 Generate Pod::Functions from perlfunc.pod This avoids it getting out of synchronisation. M ext/Pod-Functions/Functions_pm.PL ----------------------------------------------------------------------- Summary of changes: ext/Pod-Functions/Functions_pm.PL | 361 +++++++++++-------------------------- 1 files changed, 104 insertions(+), 257 deletions(-) diff --git a/ext/Pod-Functions/Functions_pm.PL b/ext/Pod-Functions/Functions_pm.PL index e65c4ae..882f923 100644 --- a/ext/Pod-Functions/Functions_pm.PL +++ b/ext/Pod-Functions/Functions_pm.PL @@ -1,5 +1,6 @@ #!perl -w use strict; +use Pod::Simple::SimpleTree; # blead will run this with miniperl, hence we can't use autodie my $real = 'Functions.pm'; @@ -11,11 +12,85 @@ 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__ +my (%Kinds, %Flavor, @Types); + +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 + push @Types, [$text, $item_text]; + + 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; + } + } else { + $item_text =~ s/ .*//; + $Flavor{$item_text} = $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. Ignoring _ sorts +# everything the way we want. +sub sort_funcs { + map { $_->[0] } + sort { $a->[1] cmp $b->[1] || $b->[0] cmp $a->[0] } + map { my $f = uc $_; $f =~ tr/_//d; [ $_, $f ] } + @_; +} + +print $fh <<'EOT'; package Pod::Functions; use strict; @@ -82,27 +157,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]; @@ -110,12 +174,12 @@ foreach ( while (<DATA>) { chomp; - s/#.*//; + s/^#.*//; next unless $_; - my($name, $type, $text) = split " ", $_, 3; - $Type{$name} = $type; - $Flavor{$name} = $text; - for my $t ( split /[,\s]+/, $type ) { + my($name, @data) = split "\t", $_; + $Flavor{$name} = pop @data; + $Type{$name} = join ',', @data; + for my $t (@data) { push @{$Kinds{$t}}, $name; } } @@ -144,230 +208,13 @@ 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}; + print $fh join("\t", $func, @{$Type{$func}}, $desc), "\n"; +} + +close $fh or die "Can't close '$temp': $!"; +rename $temp, $real or die "Can't rename '$temp' to '$real': $!"; -- Perl5 Master Repository
