This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix missing functions when splitting perlfunc
[perl5.git] / lib / Pod / Functions.pm
1 package Pod::Functions;
2 use strict;
3
4 =head1 NAME
5
6 Pod::Functions - Group Perl's functions a la perlfunc.pod
7
8 =head1 SYNOPSIS
9
10     use Pod::Functions;
11     
12     my @misc_ops = @{ $Kinds{ 'Misc' } };
13     my $misc_dsc = $Type_Description{ 'Misc' };
14
15 or
16
17     perl /path/to/lib/Pod/Functions.pm
18
19 This will print a grouped list of Perl's functions, like the 
20 L<perlfunc/"Perl Functions by Category"> section.
21
22 =head1 DESCRIPTION
23
24 It exports the following variables:
25
26 =over 4
27
28 =item %Kinds
29
30 This holds a hash-of-lists. Each list contains the functions in the catagory
31 the key denotes.
32
33 =item %Type
34
35 In this hash each key represents a function and the value is the catagory.
36 The catagory can be a comma separated list.
37
38 =item %Flavor
39
40 In this hash each key represents a function and the value is a short 
41 description of that function.
42
43 =item %Type_Description
44
45 In this hash each key represents a catagory of functions and the value is 
46 a short description of that catagory.
47
48 =item @Type_Order
49
50 This list of catagories is used to produce the same order as the
51 L<perlfunc/"Perl Functions by Category"> section.
52
53 =back
54
55 =head1 CHANGES
56
57 1.02 20020813 <abe@ztreet.demon.nl>
58     de-typo in the SYNOPSIS section (thanks Mike Castle for noticing)
59
60 1.01 20011229 <abe@ztreet.demon.nl>
61     fixed some bugs that slipped in after 5.6.1
62     added the pod
63     finished making it strict safe
64
65 1.00 ??
66     first numbered version
67
68 =cut
69
70 our $VERSION = '1.02';
71
72 require Exporter;
73
74 our @ISA = qw(Exporter);
75 our @EXPORT = qw(%Kinds %Type %Flavor %Type_Description @Type_Order);
76
77 our(%Kinds, %Type, %Flavor);
78
79 our %Type_Description = (
80     'ARRAY'     => 'Functions for real @ARRAYs',
81     'Binary'    => 'Functions for fixed length data or records',
82     'File'      => 'Functions for filehandles, files, or directories',
83     'Flow'      => 'Keywords related to control flow of your perl program',
84     'HASH'      => 'Functions for real %HASHes',
85     'I/O'       => 'Input and output functions',
86     'LIST'      => 'Functions for list data',
87     'Math'      => 'Numeric functions',
88     'Misc'      => 'Miscellaneous functions',
89     'Modules'   => 'Keywords related to perl modules',
90     'Network'   => 'Fetching network info',
91     'Objects'   => 'Keywords related to classes and object-orientedness',
92     'Process'   => 'Functions for processes and process groups',
93     'Regexp'    => 'Regular expressions and pattern matching',
94     'Socket'    => 'Low-level socket functions',
95     'String'    => 'Functions for SCALARs or strings',
96     'SysV'      => 'System V interprocess communication functions',
97     'Time'      => 'Time-related functions',
98     'User'      => 'Fetching user and group info',
99     'Namespace' => 'Keywords altering or affecting scoping of identifiers',
100 );
101
102 our @Type_Order = qw{
103     String
104     Regexp
105     Math
106     ARRAY
107     LIST
108     HASH
109     I/O
110     Binary
111     File
112     Flow
113     Namespace
114     Misc
115     Process
116     Modules
117     Objects
118     Socket
119     SysV
120     User
121     Network
122     Time
123 };
124
125 while (<DATA>) {
126     chomp;
127     s/#.*//;
128     next unless $_;
129     my($name, $type, $text) = split " ", $_, 3;
130     $Type{$name} = $type;
131     $Flavor{$name} = $text;
132     for my $t ( split /[,\s]+/, $type ) {
133         push @{$Kinds{$t}}, $name;
134     }
135 }
136
137 close DATA;
138
139 my( $typedesc, $list );
140 unless (caller) { 
141     foreach my $type ( @Type_Order ) {
142         $list = join(", ", sort @{$Kinds{$type}});
143         $typedesc = $Type_Description{$type} . ":";
144         write;
145     } 
146 }
147
148 format = 
149
150 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
151     $typedesc 
152 ~~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
153     $typedesc 
154  ~~  ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
155         $list
156 .
157
158 1;
159
160 __DATA__
161 -X      File    a file test (-r, -x, etc)
162 abs     Math    absolute value function
163 accept  Socket  accept an incoming socket connect
164 alarm   Process schedule a SIGALRM 
165 atan2   Math    arctangent of Y/X in the range -PI to PI
166 bind    Socket  binds an address to a socket
167 binmode I/O     prepare binary files for I/O
168 bless   Objects create an object 
169 caller  Flow,Namespace  get context of the current subroutine call
170 chdir   File    change your current working directory
171 chmod   File    changes the permissions on a list of files
172 chomp   String  remove a trailing record separator from a string
173 chop    String  remove the last character from a string
174 chown   File    change the owership on a list of files
175 chr     String  get character this number represents
176 chroot  File    make directory new root for path lookups
177 close   I/O     close file (or pipe or socket) handle
178 closedir        I/O     close directory handle
179 connect Socket  connect to a remote socket
180 continue        Flow    optional trailing block in a while or foreach 
181 cos     Math    cosine function
182 crypt   String  one-way passwd-style encryption
183 dbmclose        Objects,I/O     breaks binding on a tied dbm file
184 dbmopen Objects,I/O     create binding on a tied dbm file
185 defined Misc    test whether a value, variable, or function is defined
186 delete  HASH    deletes a value from a hash
187 die     I/O,Flow        raise an exception or bail out
188 do      Flow,Modules    turn a BLOCK into a TERM
189 dump    Misc,Flow       create an immediate core dump
190 each    HASH    retrieve the next key/value pair from a hash
191 endgrent        User    be done using group file
192 endhostent      User    be done using hosts file
193 endnetent       User    be done using networks file
194 endprotoent     Network be done using protocols file
195 endpwent        User    be done using passwd file
196 endservent      Network be done using services file
197 eof     I/O     test a filehandle for its end
198 eval    Flow,Misc       catch exceptions or compile and run code
199 exec    Process abandon this program to run another
200 exists  HASH    test whether a hash key is present
201 exit    Flow    terminate this program
202 exp     Math    raise I<e> to a power
203 fcntl   File    file control system call
204 fileno  I/O     return file descriptor from filehandle
205 flock   I/O     lock an entire file with an advisory lock
206 fork    Process create a new process just like this one
207 format  I/O     declare a picture format with use by the write() function
208 formline        Misc    internal function used for formats
209 getc    I/O     get     the next character from the filehandle
210 getgrent        User    get next group record 
211 getgrgid        User    get group record given group user ID
212 getgrnam        User    get group record given group name
213 gethostbyaddr   Network get host record given its address
214 gethostbyname   Network get host record given name
215 gethostent      Network get next hosts record 
216 getlogin        User    return who logged in at this tty
217 getnetbyaddr    Network get network record given its address
218 getnetbyname    Network get networks record given name
219 getnetent       Network get next networks record 
220 getpeername     Socket  find the other end of a socket connection
221 getpgrp Process get process group
222 getppid Process get parent process ID
223 getpriority     Process get current nice value
224 getprotobyname  Network get protocol record given name
225 getprotobynumber        Network get protocol record numeric protocol
226 getprotoent     Network get next protocols record
227 getpwent        User    get next passwd record
228 getpwnam        User    get passwd record given user login name
229 getpwuid        User    get passwd record given user ID
230 getservbyname   Network get services record given its name
231 getservbyport   Network get services record given numeric port
232 getservent      Network get next services record 
233 getsockname     Socket  retrieve the sockaddr for a given socket
234 getsockopt      Socket  get socket options on a given socket
235 glob    File            expand filenames using wildcards
236 gmtime  Time    convert UNIX time into record or string using Greenwich time
237 goto    Flow    create spaghetti code
238 grep    LIST    locate elements in a list test true against a given criterion
239 hex     Math,String     convert a string to a hexadecimal number
240 import  Modules,Namespace       patch a module's namespace into your own
241 index   String  find a substring within a string
242 int     Math    get the integer portion of a number
243 ioctl   File    system-dependent device control system call
244 join    LIST    join a list into a string using a separator
245 keys    HASH    retrieve list of indices from a hash
246 kill    Process send a signal to a process or process group
247 last    Flow    exit a block prematurely
248 lc      String  return lower-case version of a string
249 lcfirst String  return a string with just the next letter in lower case
250 length  String  return the number of bytes in a string
251 link    File    create a hard link in the filesytem
252 listen  Socket  register your socket as a server 
253 local   Misc,Namespace  create a temporary value for a global variable (dynamic scoping)
254 localtime       Time    convert UNIX time into record or string using local time
255 lock    Threads get a thread lock on a variable, subroutine, or method
256 log     Math    retrieve the natural logarithm for a number
257 lstat   File    stat a symbolic link
258 m//     Regexp  match a string with a regular expression pattern
259 map     LIST    apply a change to a list to get back a new list with the changes
260 mkdir   File    create a directory
261 msgctl  SysV    SysV IPC message control operations
262 msgget  SysV    get SysV IPC message queue
263 msgrcv  SysV    receive a SysV IPC message from a message queue
264 msgsnd  SysV    send a SysV IPC message to a message queue
265 my      Misc,Namespace  declare and assign a local variable (lexical scoping)
266 next    Flow    iterate a block prematurely
267 no      Modules unimport some module symbols or semantics at compile time
268 package Modules,Objects,Namespace       declare a separate global namespace
269 prototype       Flow,Misc       get the prototype (if any) of a subroutine
270 oct     String,Math     convert a string to an octal number
271 open    File    open a file, pipe, or descriptor
272 opendir File    open a directory
273 ord     String  find a character's numeric representation
274 our     Misc,Namespace  declare and assign a package variable (lexical scoping)
275 pack    Binary,String   convert a list into a binary representation
276 pipe    Process open a pair of connected filehandles
277 pop     ARRAY   remove the last element from an array and return it
278 pos     Regexp  find or set the offset for the last/next m//g search
279 print   I/O     output a list to a filehandle
280 printf  I/O     output a formatted list to a filehandle
281 push    ARRAY   append one or more elements to an array
282 q/STRING/       String  singly quote a string
283 qq/STRING/      String  doubly quote a string
284 quotemeta       Regexp  quote regular expression magic characters
285 qw/STRING/      LIST    quote a list of words
286 qx/STRING/      Process backquote quote a string
287 qr/STRING/      Regexp  Compile pattern 
288 rand    Math    retrieve the next pseudorandom number 
289 read    I/O,Binary      fixed-length buffered input from a filehandle
290 readdir I/O     get a directory from a directory handle
291 readline        I/O     fetch a record from a file
292 readlink        File    determine where a symbolic link is pointing
293 readpipe        Process execute a system command and collect standard output
294 recv    Socket  receive a message over a Socket
295 redo    Flow    start this loop iteration over again
296 ref     Objects find out the type of thing being referenced
297 rename  File    change a filename
298 require Modules load in external functions from a library at runtime
299 reset   Misc    clear all variables of a given name
300 return  Flow    get out of a function early
301 reverse String,LIST     flip a string or a list
302 rewinddir       I/O     reset directory handle
303 rindex  String  right-to-left substring search
304 rmdir   File    remove a directory
305 s///    Regexp  replace a pattern with a string
306 scalar  Misc    force a scalar context
307 seek    I/O     reposition file pointer for random-access I/O
308 seekdir I/O     reposition directory pointer 
309 select  I/O     reset default output or do I/O multiplexing
310 semctl  SysV    SysV semaphore control operations
311 semget  SysV    get set of SysV semaphores
312 semop   SysV    SysV semaphore operations
313 send    Socket  send a message over a socket
314 setgrent        User    prepare group file for use
315 sethostent      Network prepare hosts file for use
316 setnetent       Network prepare networks file for use
317 setpgrp Process set the process group of a process
318 setpriority     Process set a process's nice value
319 setprotoent     Network prepare protocols file for use
320 setpwent        User    prepare passwd file for use
321 setservent      Network prepare services file for use
322 setsockopt      Socket  set some socket options
323 shift   ARRAY   remove the first element of an array, and return it
324 shmctl  SysV    SysV shared memory operations
325 shmget  SysV    get SysV shared memory segment identifier
326 shmread SysV    read SysV shared memory 
327 shmwrite        SysV    write SysV shared memory 
328 shutdown        Socket  close down just half of a socket connection
329 sin     Math    return the sine of a number
330 sleep   Process block for some number of seconds
331 socket  Socket  create a socket
332 socketpair      Socket  create a pair of sockets
333 sort    LIST    sort a list of values 
334 splice  ARRAY   add or remove elements anywhere in an array
335 split   Regexp  split up a string using a regexp delimiter
336 sprintf String  formatted print into a string   
337 sqrt    Math    square root function
338 srand   Math    seed the random number generator
339 stat    File    get a file's status information
340 study   Regexp  optimize input data for repeated searches
341 sub     Flow    declare a subroutine, possibly anonymously
342 substr  String  get or alter a portion of a stirng
343 symlink File    create a symbolic link to a file
344 syscall I/O,Binary      execute an arbitrary system call
345 sysopen File    open a file, pipe, or descriptor
346 sysread I/O,Binary      fixed-length unbuffered input from a filehandle
347 sysseek I/O,Binary      position I/O pointer on handle used with sysread and syswrite
348 system  Process run a separate program 
349 syswrite        I/O,Binary      fixed-length unbuffered output to a filehandle
350 tell    I/O     get current seekpointer on a filehandle
351 telldir I/O     get current seekpointer on a directory handle
352 tie     Objects bind a variable to an object class 
353 tied    Objects get a reference to the object underlying a tied variable
354 time    Time    return number of seconds since 1970
355 times   Process,Time    return elapsed time for self and child processes
356 tr///   String  transliterate a string
357 truncate        I/O     shorten a file
358 uc      String  return upper-case version of a string
359 ucfirst String  return a string with just the next letter in upper case
360 umask   File    set file creation mode mask
361 undef   Misc    remove a variable or function definition
362 unlink  File    remove one link to a file
363 unpack  Binary,LIST     convert binary structure into normal perl variables
364 unshift ARRAY   prepend more elements to the beginning of a list
365 untie   Objects break a tie binding to a variable
366 use     Modules,Namespace       load a module and import its namespace
367 use     Objects load in a module at compile time
368 utime   File    set a file's last access and modify times
369 values  HASH    return a list of the values in a hash
370 vec     Binary  test or set particular bits in a string
371 wait    Process wait for any child process to die
372 waitpid Process wait for  a particular child process to die
373 wantarray       Misc,Flow       get void vs scalar vs list context of current subroutine call
374 warn    I/O     print debugging info
375 write   I/O     print a picture record
376 y///    String  transliterate a string