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