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