1#!../miniperl 2 3use strict; 4use warnings; 5 6local $ENV{LC_ALL} = 'C'; 7 8my $Quiet; 9@ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV; 10 11if (@ARGV) { 12 my $workdir = shift; 13 chdir $workdir 14 or die "Couldn't chdir to '$workdir': $!"; 15} 16require './regen/regen_lib.pl'; 17 18# MANIFEST itself is Unix style filenames, so we have to assume that Unix style 19# filenames will work. 20 21open MANIFEST, '<', 'MANIFEST' 22 or die "Can't open MANIFEST: $!"; 23my @files = 24 grep !m#/perl.*\.pod#, 25 grep m#(?:\.pm|\.pod|_pm\.PL)#, 26 map {s/\s.*//s; $_} 27 grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo|corpus)/# } 28 <MANIFEST>; 29close MANIFEST 30 or die "$0: failed to close MANIFEST: $!"; 31 32my $out = open_new('pod/perlmodlib.pod', undef, 33 {by => "$0 extracting documentation", 34 from => 'the Perl source files'}, 1); 35 36my %exceptions = ( 37 'abbrev' => 'Text::Abbrev', 38 'carp' => 'Carp', 39 'getopt' => 'Getopt::Std', 40 'Encode::MIME::NAME' => 'Encode::MIME::Name', 41 'libnetFAQ' => 'Net::libnetFAQ', 42); 43 44my (@pragma, @mod); 45 46for my $filename (@files) { 47 unless (open MOD, '<', $filename) { 48 warn "Couldn't open $filename: $!"; 49 next; 50 } 51 52 my ($name, $thing); 53 my $foundit = 0; 54 { 55 local $/ = ""; 56 while (<MOD>) { 57 next unless /^=head1 NAME/; 58 $foundit++; 59 last; 60 } 61 } 62 unless ($foundit) { 63 next if pod_for_module_has_head1_NAME($filename); 64 die "p5p-controlled module $filename missing =head1 NAME\n" 65 if $filename !~ m{^(dist/|cpan/)}n # under our direct control 66 && $filename !~ m{/_[^/]+\z} # not private 67 && $filename !~ m{/unicore/} # not unicore 68 && $filename ne 'lib/meta_notation.pm' # no pod 69 && $filename ne 'lib/overload/numbers.pm'; # no pod 70 warn "$filename missing =head1 NAME\n" unless $Quiet; 71 next; 72 } 73 my $title = <MOD>; 74 chomp $title; 75 close MOD 76 or die "Error closing $filename: $!"; 77 78 ($name, $thing) = split /\s+--?\s+/, $title, 2; 79 80 unless ($name and $thing) { 81 warn "$filename missing name\n" unless $name; 82 warn "$filename missing thing\n" unless $thing or $Quiet; 83 next; 84 } 85 86 $name =~ s/[^A-Za-z0-9_:\$<>].*//; 87 $name = $exceptions{$name} || $name; 88 $thing =~ s/^perl pragma to //i; 89 $thing = ucfirst $thing; 90 $title = "=item $name\n\n$thing\n\n"; 91 92 if ($name =~ /[A-Z]/) { 93 push @mod, $title; 94 } else { 95 push @pragma, $title; 96 } 97} 98 99sub pod_for_module_has_head1_NAME { 100 my ($filename) = @_; 101 (my $pod_file = $filename) =~ s/\.pm\z/.pod/ or return 0; 102 return 0 if !-e $pod_file; 103 open my $fh, '<', $pod_file 104 or die "Can't open $pod_file for reading: $!\n"; 105 local $/ = ''; 106 while (my $para = <$fh>) { 107 return 1 if $para =~ /\A=head1 NAME$/m; 108 } 109 return 0; 110} 111 112# Much easier to special case it like this than special case the depending on 113# and parsing lib/Config.pod, or special case opening configpm and finding its 114# =head1 (which is not found with the $/="" above) 115push @mod, "=item Config\n\nAccess Perl configuration information\n\n"; 116 117 118# The intent of using =cut as the heredoc terminator is to make the whole file 119# parse as (reasonably) sane Pod as-is to anything that attempts to 120# brute-force treat it as such. The content is already useful - this just 121# makes it tidier, by stopping anything doing this mistaking the rest of the 122# Perl code for Pod. eg https://metacpan.org/pod/perlmodlib 123 124print $out <<'=cut'; 125=head1 NAME 126 127perlmodlib - constructing new Perl modules and finding existing ones 128 129=head1 THE PERL MODULE LIBRARY 130 131Many modules are included in the Perl distribution. These are described 132below, and all end in F<.pm>. You may discover compiled library 133files (usually ending in F<.so>) or small pieces of modules to be 134autoloaded (ending in F<.al>); these were automatically generated 135by the installation process. You may also discover files in the 136library directory that end in either F<.pl> or F<.ph>. These are 137old libraries supplied so that old programs that use them still 138run. The F<.pl> files will all eventually be converted into standard 139modules, and the F<.ph> files made by B<h2ph> will probably end up 140as extension modules made by B<h2xs>. (Some F<.ph> values may 141already be available through the POSIX, Errno, or Fcntl modules.) 142The B<pl2pm> file in the distribution may help in your conversion, 143but it's just a mechanical process and therefore far from bulletproof. 144 145=head2 Pragmatic Modules 146 147They work somewhat like compiler directives (pragmata) in that they 148tend to affect the compilation of your program, and thus will usually 149work well only when used within a C<use>, or C<no>. Most of these 150are lexically scoped, so an inner BLOCK may countermand them 151by saying: 152 153 no integer; 154 no strict 'refs'; 155 no warnings; 156 157which lasts until the end of that BLOCK. 158 159Some pragmas are lexically scoped--typically those that affect the 160C<$^H> hints variable. Others affect the current package instead, 161like C<use vars> and C<use subs>, which allow you to predeclare a 162variables or subroutines within a particular I<file> rather than 163just a block. Such declarations are effective for the entire file 164for which they were declared. You cannot rescind them with C<no 165vars> or C<no subs>. 166 167The following pragmas are defined (and have their own documentation). 168 169=over 12 170 171=cut 172 173print $out $_ for sort @pragma; 174 175print $out <<'=cut'; 176 177=back 178 179=head2 Standard Modules 180 181Standard, bundled modules are all expected to behave in a well-defined 182manner with respect to namespace pollution because they use the 183Exporter module. See their own documentation for details. 184 185It's possible that not all modules listed below are installed on your 186system. For example, the GDBM_File module will not be installed if you 187don't have the gdbm library. 188 189=over 12 190 191=cut 192 193print $out $_ for sort @mod; 194 195print $out <<'=cut', "=cut\n"; 196 197=back 198 199To find out I<all> modules installed on your system, including 200those without documentation or outside the standard release, 201just use the following command (under the default win32 shell, 202double quotes should be used instead of single quotes). 203 204 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \ 205 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, 206 no_chdir => 1 }, @INC' 207 208(The -T is here to prevent '.' from being listed in @INC.) 209They should all have their own documentation installed and accessible 210via your system man(1) command. If you do not have a B<find> 211program, you can use the Perl B<find2perl> program instead, which 212generates Perl code as output you can run through perl. If you 213have a B<man> program but it doesn't find your modules, you'll have 214to fix your manpath. See L<perl> for details. If you have no 215system B<man> command, you might try the B<perldoc> program. 216 217Note also that the command C<perldoc perllocal> gives you a (possibly 218incomplete) list of the modules that have been further installed on 219your system. (The perllocal.pod file is updated by the standard MakeMaker 220install process.) 221 222=head2 Extension Modules 223 224Extension modules are written in C (or a mix of Perl and C). They 225are usually dynamically loaded into Perl if and when you need them, 226but may also be linked in statically. Supported extension modules 227include Socket, Fcntl, and POSIX. 228 229Many popular C extension modules do not come bundled (at least, not 230completely) due to their sizes, volatility, or simply lack of time 231for adequate testing and configuration across the multitude of 232platforms on which Perl was beta-tested. You are encouraged to 233look for them on CPAN (described below), or using web search engines 234like Google or DuckDuckGo. 235 236=head1 CPAN 237 238CPAN stands for Comprehensive Perl Archive Network; it's a globally 239replicated trove of Perl materials, including documentation, style 240guides, tricks and traps, alternate ports to non-Unix systems and 241occasional binary distributions for these. Search engines for 242CPAN can be found at http://www.cpan.org/ 243 244Most importantly, CPAN includes around a thousand unbundled modules, 245some of which require a C compiler to build. Major categories of 246modules are: 247 248=over 249 250=item * 251 252Language Extensions and Documentation Tools 253 254=item * 255 256Development Support 257 258=item * 259 260Operating System Interfaces 261 262=item * 263 264Networking, Device Control (modems) and InterProcess Communication 265 266=item * 267 268Data Types and Data Type Utilities 269 270=item * 271 272Database Interfaces 273 274=item * 275 276User Interfaces 277 278=item * 279 280Interfaces to / Emulations of Other Programming Languages 281 282=item * 283 284File Names, File Systems and File Locking (see also File Handles) 285 286=item * 287 288String Processing, Language Text Processing, Parsing, and Searching 289 290=item * 291 292Option, Argument, Parameter, and Configuration File Processing 293 294=item * 295 296Internationalization and Locale 297 298=item * 299 300Authentication, Security, and Encryption 301 302=item * 303 304World Wide Web, HTML, HTTP, CGI, MIME 305 306=item * 307 308Server and Daemon Utilities 309 310=item * 311 312Archiving and Compression 313 314=item * 315 316Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing 317 318=item * 319 320Mail and Usenet News 321 322=item * 323 324Control Flow Utilities (callbacks and exceptions etc) 325 326=item * 327 328File Handle and Input/Output Stream Utilities 329 330=item * 331 332Miscellaneous Modules 333 334=back 335 336The list of the registered CPAN sites follows. 337Please note that the sorting order is alphabetical on fields: 338 339Continent 340 | 341 |-->Country 342 | 343 |-->[state/province] 344 | 345 |-->ftp 346 | 347 |-->[http] 348 349and thus the North American servers happen to be listed between the 350European and the South American sites. 351 352Registered CPAN sites 353 354=for maintainers 355Generated by Porting/make_modlib_cpan.pl 356 357=head2 Africa 358 359=over 4 360 361=item South Africa 362 363 http://mirror.is.co.za/pub/cpan/ 364 ftp://ftp.is.co.za/pub/cpan/ 365 http://cpan.mirror.ac.za/ 366 ftp://cpan.mirror.ac.za/ 367 http://cpan.saix.net/ 368 ftp://ftp.saix.net/pub/CPAN/ 369 http://ftp.wa.co.za/pub/CPAN/ 370 ftp://ftp.wa.co.za/pub/CPAN/ 371 372=item Uganda 373 374 http://mirror.ucu.ac.ug/cpan/ 375 376=item Zimbabwe 377 378 http://mirror.zol.co.zw/CPAN/ 379 ftp://mirror.zol.co.zw/CPAN/ 380 381=back 382 383=head2 Asia 384 385=over 4 386 387=item Bangladesh 388 389 http://mirror.dhakacom.com/CPAN/ 390 ftp://mirror.dhakacom.com/CPAN/ 391 392=item China 393 394 http://cpan.communilink.net/ 395 http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/ 396 ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/ 397 http://mirrors.hust.edu.cn/CPAN/ 398 http://mirrors.neusoft.edu.cn/cpan/ 399 http://mirror.lzu.edu.cn/CPAN/ 400 http://mirrors.163.com/cpan/ 401 http://mirrors.sohu.com/CPAN/ 402 http://mirrors.ustc.edu.cn/CPAN/ 403 ftp://mirrors.ustc.edu.cn/CPAN/ 404 http://mirrors.xmu.edu.cn/CPAN/ 405 ftp://mirrors.xmu.edu.cn/CPAN/ 406 http://mirrors.zju.edu.cn/CPAN/ 407 408=item India 409 410 http://cpan.excellmedia.net/ 411 http://perlmirror.indialinks.com/ 412 413=item Indonesia 414 415 http://kambing.ui.ac.id/cpan/ 416 http://cpan.pesat.net.id/ 417 http://mirror.poliwangi.ac.id/CPAN/ 418 http://kartolo.sby.datautama.net.id/CPAN/ 419 http://mirror.wanxp.id/cpan/ 420 421=item Iran 422 423 http://mirror.yazd.ac.ir/cpan/ 424 425=item Israel 426 427 http://biocourse.weizmann.ac.il/CPAN/ 428 429=item Japan 430 431 http://ftp.jaist.ac.jp/pub/CPAN/ 432 ftp://ftp.jaist.ac.jp/pub/CPAN/ 433 http://mirror.jre655.com/CPAN/ 434 ftp://mirror.jre655.com/CPAN/ 435 ftp://ftp.kddilabs.jp/CPAN/ 436 http://ftp.nara.wide.ad.jp/pub/CPAN/ 437 ftp://ftp.nara.wide.ad.jp/pub/CPAN/ 438 http://ftp.riken.jp/lang/CPAN/ 439 ftp://ftp.riken.jp/lang/CPAN/ 440 ftp://ftp.u-aizu.ac.jp/pub/CPAN/ 441 http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/ 442 ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/ 443 444=item Kazakhstan 445 446 http://mirror.neolabs.kz/CPAN/ 447 ftp://mirror.neolabs.kz/CPAN/ 448 449=item Philippines 450 451 http://mirror.pregi.net/CPAN/ 452 ftp://mirror.pregi.net/CPAN/ 453 http://mirror.rise.ph/cpan/ 454 ftp://mirror.rise.ph/cpan/ 455 456=item Qatar 457 458 http://mirror.qnren.qa/CPAN/ 459 ftp://mirror.qnren.qa/CPAN/ 460 461=item Republic of Korea 462 463 http://cpan.mirror.cdnetworks.com/ 464 ftp://cpan.mirror.cdnetworks.com/CPAN/ 465 http://ftp.kaist.ac.kr/pub/CPAN/ 466 ftp://ftp.kaist.ac.kr/CPAN/ 467 http://ftp.kr.freebsd.org/pub/CPAN/ 468 ftp://ftp.kr.freebsd.org/pub/CPAN/ 469 http://mirror.navercorp.com/CPAN/ 470 http://ftp.neowiz.com/CPAN/ 471 ftp://ftp.neowiz.com/CPAN/ 472 473=item Singapore 474 475 http://cpan.mirror.choon.net/ 476 http://mirror.0x.sg/CPAN/ 477 ftp://mirror.0x.sg/CPAN/ 478 479=item Taiwan 480 481 http://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/ 482 ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/ 483 http://cpan.stu.edu.tw/ 484 ftp://ftp.stu.edu.tw/CPAN/ 485 http://ftp.yzu.edu.tw/CPAN/ 486 ftp://ftp.yzu.edu.tw/CPAN/ 487 http://cpan.nctu.edu.tw/ 488 ftp://cpan.nctu.edu.tw/ 489 http://ftp.ubuntu-tw.org/mirror/CPAN/ 490 ftp://ftp.ubuntu-tw.org/mirror/CPAN/ 491 492=item Turkey 493 494 http://cpan.ulak.net.tr/ 495 ftp://ftp.ulak.net.tr/pub/perl/CPAN/ 496 http://mirror.vit.com.tr/mirror/CPAN/ 497 ftp://mirror.vit.com.tr/CPAN/ 498 499=item Viet Nam 500 501 http://mirrors.digipower.vn/CPAN/ 502 http://mirror.downloadvn.com/cpan/ 503 http://mirrors.vinahost.vn/CPAN/ 504 505=back 506 507=head2 Europe 508 509=over 4 510 511=item Austria 512 513 http://cpan.inode.at/ 514 ftp://cpan.inode.at/ 515 http://mirror.easyname.at/cpan/ 516 ftp://mirror.easyname.at/cpan/ 517 http://gd.tuwien.ac.at/languages/perl/CPAN/ 518 ftp://gd.tuwien.ac.at/pub/CPAN/ 519 520=item Belarus 521 522 http://ftp.byfly.by/pub/CPAN/ 523 ftp://ftp.byfly.by/pub/CPAN/ 524 http://mirror.datacenter.by/pub/CPAN/ 525 ftp://mirror.datacenter.by/pub/CPAN/ 526 527=item Belgium 528 529 http://ftp.belnet.be/ftp.cpan.org/ 530 ftp://ftp.belnet.be/mirror/ftp.cpan.org/ 531 http://cpan.cu.be/ 532 http://lib.ugent.be/CPAN/ 533 http://cpan.weepeetelecom.be/ 534 535=item Bosnia and Herzegovina 536 537 http://cpan.mirror.ba/ 538 ftp://ftp.mirror.ba/CPAN/ 539 540=item Bulgaria 541 542 http://mirrors.neterra.net/CPAN/ 543 ftp://mirrors.neterra.net/CPAN/ 544 http://mirrors.netix.net/CPAN/ 545 ftp://mirrors.netix.net/CPAN/ 546 547=item Croatia 548 549 http://ftp.carnet.hr/pub/CPAN/ 550 ftp://ftp.carnet.hr/pub/CPAN/ 551 552=item Czech Republic 553 554 http://mirror.dkm.cz/cpan/ 555 ftp://mirror.dkm.cz/cpan/ 556 ftp://ftp.fi.muni.cz/pub/CPAN/ 557 http://mirrors.nic.cz/CPAN/ 558 ftp://mirrors.nic.cz/pub/CPAN/ 559 http://cpan.mirror.vutbr.cz/ 560 ftp://mirror.vutbr.cz/cpan/ 561 562=item Denmark 563 564 http://www.cpan.dk/ 565 http://mirrors.dotsrc.org/cpan/ 566 ftp://mirrors.dotsrc.org/cpan/ 567 568=item Finland 569 570 ftp://ftp.funet.fi/pub/languages/perl/CPAN/ 571 572=item France 573 574 http://ftp.ciril.fr/pub/cpan/ 575 ftp://ftp.ciril.fr/pub/cpan/ 576 http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ 577 ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ 578 http://ftp.lip6.fr/pub/perl/CPAN/ 579 ftp://ftp.lip6.fr/pub/perl/CPAN/ 580 http://mirror.ibcp.fr/pub/CPAN/ 581 ftp://ftp.oleane.net/pub/CPAN/ 582 http://cpan.mirrors.ovh.net/ftp.cpan.org/ 583 ftp://cpan.mirrors.ovh.net/ftp.cpan.org/ 584 http://cpan.enstimac.fr/ 585 586=item Germany 587 588 http://mirror.23media.de/cpan/ 589 ftp://mirror.23media.de/cpan/ 590 http://artfiles.org/cpan.org/ 591 ftp://artfiles.org/cpan.org/ 592 http://mirror.bibleonline.ru/cpan/ 593 http://mirror.checkdomain.de/CPAN/ 594 ftp://mirror.checkdomain.de/CPAN/ 595 http://cpan.noris.de/ 596 http://mirror.de.leaseweb.net/CPAN/ 597 ftp://mirror.de.leaseweb.net/CPAN/ 598 http://cpan.mirror.euserv.net/ 599 ftp://mirror.euserv.net/cpan/ 600 http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/ 601 ftp://mirror.fraunhofer.de/CPAN/ 602 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ 603 http://ftp.hosteurope.de/pub/CPAN/ 604 ftp://ftp.hosteurope.de/pub/CPAN/ 605 ftp://ftp.fu-berlin.de/unix/languages/perl/ 606 http://ftp.gwdg.de/pub/languages/perl/CPAN/ 607 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ 608 http://ftp.hawo.stw.uni-erlangen.de/CPAN/ 609 ftp://ftp.hawo.stw.uni-erlangen.de/CPAN/ 610 http://cpan.mirror.iphh.net/ 611 ftp://cpan.mirror.iphh.net/pub/CPAN/ 612 ftp://ftp.mpi-inf.mpg.de/pub/perl/CPAN/ 613 http://cpan.netbet.org/ 614 http://mirror.netcologne.de/cpan/ 615 ftp://mirror.netcologne.de/cpan/ 616 ftp://mirror.petamem.com/CPAN/ 617 http://www.planet-elektronik.de/CPAN/ 618 http://ftp.halifax.rwth-aachen.de/cpan/ 619 ftp://ftp.halifax.rwth-aachen.de/cpan/ 620 http://mirror.softaculous.com/cpan/ 621 http://ftp.u-tx.net/CPAN/ 622 ftp://ftp.u-tx.net/CPAN/ 623 http://mirror.reismil.ch/CPAN/ 624 625=item Greece 626 627 http://cpan.cc.uoc.gr/mirrors/CPAN/ 628 ftp://ftp.cc.uoc.gr/mirrors/CPAN/ 629 http://ftp.ntua.gr/pub/lang/perl/ 630 ftp://ftp.ntua.gr/pub/lang/perl/ 631 632=item Hungary 633 634 http://mirror.met.hu/CPAN/ 635 636=item Ireland 637 638 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/ 639 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/ 640 641=item Italy 642 643 http://bo.mirror.garr.it/mirrors/CPAN/ 644 ftp://ftp.eutelia.it/CPAN_Mirror/ 645 http://cpan.panu.it/ 646 ftp://ftp.panu.it/pub/mirrors/perl/CPAN/ 647 http://cpan.muzzy.it/ 648 649=item Latvia 650 651 http://kvin.lv/pub/CPAN/ 652 653=item Lithuania 654 655 http://ftp.litnet.lt/pub/CPAN/ 656 ftp://ftp.litnet.lt/pub/CPAN/ 657 658=item Moldova 659 660 http://mirror.as43289.net/pub/CPAN/ 661 ftp://mirror.as43289.net/pub/CPAN/ 662 663=item Netherlands 664 665 http://cpan.cs.uu.nl/ 666 ftp://ftp.cs.uu.nl/pub/CPAN/ 667 http://mirror.nl.leaseweb.net/CPAN/ 668 ftp://mirror.nl.leaseweb.net/CPAN/ 669 http://ftp.nluug.nl/languages/perl/CPAN/ 670 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ 671 http://mirror.transip.net/CPAN/ 672 ftp://mirror.transip.net/CPAN/ 673 http://cpan.mirror.triple-it.nl/ 674 http://ftp.tudelft.nl/cpan/ 675 ftp://ftp.tudelft.nl/pub/CPAN/ 676 ftp://download.xs4all.nl/pub/mirror/CPAN/ 677 678=item Norway 679 680 http://cpan.uib.no/ 681 ftp://cpan.uib.no/pub/CPAN/ 682 ftp://ftp.uninett.no/pub/languages/perl/CPAN/ 683 http://cpan.vianett.no/ 684 685=item Poland 686 687 http://ftp.agh.edu.pl/CPAN/ 688 ftp://ftp.agh.edu.pl/CPAN/ 689 http://ftp.piotrkosoft.net/pub/mirrors/CPAN/ 690 ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/ 691 ftp://ftp.ps.pl/pub/CPAN/ 692 http://sunsite.icm.edu.pl/pub/CPAN/ 693 ftp://sunsite.icm.edu.pl/pub/CPAN/ 694 695=item Portugal 696 697 http://cpan.dcc.fc.up.pt/ 698 http://mirrors.fe.up.pt/pub/CPAN/ 699 http://cpan.perl-hackers.net/ 700 http://cpan.perl.pt/ 701 702=item Romania 703 704 http://mirrors.hostingromania.ro/cpan.org/ 705 ftp://ftp.lug.ro/CPAN/ 706 http://mirrors.m247.ro/CPAN/ 707 http://mirrors.evowise.com/CPAN/ 708 http://mirrors.teentelecom.net/CPAN/ 709 ftp://mirrors.teentelecom.net/CPAN/ 710 http://mirrors.xservers.ro/CPAN/ 711 712=item Russian Federation 713 714 ftp://ftp.aha.ru/CPAN/ 715 http://cpan.rinet.ru/ 716 ftp://cpan.rinet.ru/pub/mirror/CPAN/ 717 http://cpan-mirror.rbc.ru/pub/CPAN/ 718 http://mirror.rol.ru/CPAN/ 719 http://cpan.uni-altai.ru/ 720 http://cpan.webdesk.ru/ 721 ftp://cpan.webdesk.ru/cpan/ 722 http://mirror.yandex.ru/mirrors/cpan/ 723 ftp://mirror.yandex.ru/mirrors/cpan/ 724 725=item Serbia 726 727 http://mirror.sbb.rs/CPAN/ 728 ftp://mirror.sbb.rs/CPAN/ 729 730=item Slovakia 731 732 http://cpan.lnx.sk/ 733 http://tux.rainside.sk/CPAN/ 734 ftp://tux.rainside.sk/CPAN/ 735 736=item Slovenia 737 738 http://ftp.arnes.si/software/perl/CPAN/ 739 ftp://ftp.arnes.si/software/perl/CPAN/ 740 741=item Spain 742 743 http://mirrors.evowise.com/CPAN/ 744 http://osl.ugr.es/CPAN/ 745 http://ftp.rediris.es/mirror/CPAN/ 746 ftp://ftp.rediris.es/mirror/CPAN/ 747 748=item Sweden 749 750 http://ftp.acc.umu.se/mirror/CPAN/ 751 ftp://ftp.acc.umu.se/mirror/CPAN/ 752 753=item Switzerland 754 755 http://www.pirbot.com/mirrors/cpan/ 756 http://mirror.switch.ch/ftp/mirror/CPAN/ 757 ftp://mirror.switch.ch/mirror/CPAN/ 758 759=item Ukraine 760 761 http://cpan.ip-connect.vn.ua/ 762 ftp://cpan.ip-connect.vn.ua/mirror/cpan/ 763 764=item United Kingdom 765 766 http://cpan.mirror.anlx.net/ 767 ftp://ftp.mirror.anlx.net/CPAN/ 768 http://mirror.bytemark.co.uk/CPAN/ 769 ftp://mirror.bytemark.co.uk/CPAN/ 770 http://mirrors.coreix.net/CPAN/ 771 http://cpan.etla.org/ 772 ftp://cpan.etla.org/pub/CPAN/ 773 http://cpan.cpantesters.org/ 774 http://mirror.sax.uk.as61049.net/CPAN/ 775 http://mirror.sov.uk.goscomb.net/CPAN/ 776 http://www.mirrorservice.org/sites/cpan.perl.org/CPAN/ 777 ftp://ftp.mirrorservice.org/sites/cpan.perl.org/CPAN/ 778 http://mirror.ox.ac.uk/sites/www.cpan.org/ 779 ftp://mirror.ox.ac.uk/sites/www.cpan.org/ 780 http://ftp.ticklers.org/pub/CPAN/ 781 ftp://ftp.ticklers.org/pub/CPAN/ 782 http://cpan.mirrors.uk2.net/ 783 ftp://mirrors.uk2.net/pub/CPAN/ 784 http://mirror.ukhost4u.com/CPAN/ 785 786=back 787 788=head2 North America 789 790=over 4 791 792=item Canada 793 794 http://CPAN.mirror.rafal.ca/ 795 ftp://CPAN.mirror.rafal.ca/pub/CPAN/ 796 http://mirror.csclub.uwaterloo.ca/CPAN/ 797 ftp://mirror.csclub.uwaterloo.ca/CPAN/ 798 http://mirrors.gossamer-threads.com/CPAN/ 799 http://mirror.its.dal.ca/cpan/ 800 ftp://mirror.its.dal.ca/cpan/ 801 ftp://ftp.ottix.net/pub/CPAN/ 802 803=item Costa Rica 804 805 http://mirrors.ucr.ac.cr/CPAN/ 806 807=item Mexico 808 809 http://www.msg.com.mx/CPAN/ 810 ftp://ftp.msg.com.mx/pub/CPAN/ 811 812=item United States 813 814=over 8 815 816=item Alabama 817 818 http://mirror.teklinks.com/CPAN/ 819 820=item Arizona 821 822 http://mirror.n5tech.com/CPAN/ 823 http://mirrors.namecheap.com/CPAN/ 824 ftp://mirrors.namecheap.com/CPAN/ 825 826=item California 827 828 http://cpan.develooper.com/ 829 http://httpupdate127.cpanel.net/CPAN/ 830 http://mirrors.sonic.net/cpan/ 831 ftp://mirrors.sonic.net/cpan/ 832 http://www.perl.com/CPAN/ 833 http://cpan.yimg.com/ 834 835=item Idaho 836 837 http://mirrors.syringanetworks.net/CPAN/ 838 ftp://mirrors.syringanetworks.net/CPAN/ 839 840=item Illinois 841 842 http://cpan.mirrors.hoobly.com/ 843 http://mirror.team-cymru.org/CPAN/ 844 ftp://mirror.team-cymru.org/CPAN/ 845 846=item Indiana 847 848 http://cpan.netnitco.net/ 849 ftp://cpan.netnitco.net/pub/mirrors/CPAN/ 850 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/ 851 852=item Kansas 853 854 http://mirrors.concertpass.com/cpan/ 855 856=item Massachusetts 857 858 http://mirrors.ccs.neu.edu/CPAN/ 859 860=item Michigan 861 862 http://cpan.cse.msu.edu/ 863 ftp://cpan.cse.msu.edu/ 864 http://httpupdate118.cpanel.net/CPAN/ 865 http://mirrors-usa.go-parts.com/cpan/ 866 http://ftp.wayne.edu/CPAN/ 867 ftp://ftp.wayne.edu/CPAN/ 868 869=item New Hampshire 870 871 http://mirror.metrocast.net/cpan/ 872 873=item New Jersey 874 875 http://mirror.datapipe.net/CPAN/ 876 ftp://mirror.datapipe.net/pub/CPAN/ 877 http://www.hoovism.com/CPAN/ 878 ftp://ftp.hoovism.com/CPAN/ 879 http://cpan.mirror.nac.net/ 880 881=item New York 882 883 http://mirror.cc.columbia.edu/pub/software/cpan/ 884 ftp://mirror.cc.columbia.edu/pub/software/cpan/ 885 http://cpan.belfry.net/ 886 http://cpan.erlbaum.net/ 887 ftp://cpan.erlbaum.net/CPAN/ 888 http://cpan.hexten.net/ 889 ftp://cpan.hexten.net/ 890 http://mirror.nyi.net/CPAN/ 891 ftp://mirror.nyi.net/pub/CPAN/ 892 http://noodle.portalus.net/CPAN/ 893 ftp://noodle.portalus.net/CPAN/ 894 http://mirrors.rit.edu/CPAN/ 895 ftp://mirrors.rit.edu/CPAN/ 896 897=item North Carolina 898 899 http://httpupdate140.cpanel.net/CPAN/ 900 http://mirrors.ibiblio.org/CPAN/ 901 902=item Oregon 903 904 http://ftp.osuosl.org/pub/CPAN/ 905 ftp://ftp.osuosl.org/pub/CPAN/ 906 http://mirror.uoregon.edu/CPAN/ 907 908=item Pennsylvania 909 910 http://cpan.pair.com/ 911 ftp://cpan.pair.com/pub/CPAN/ 912 http://cpan.mirrors.ionfish.org/ 913 914=item South Carolina 915 916 http://cpan.mirror.clemson.edu/ 917 918=item Texas 919 920 http://mirror.uta.edu/CPAN/ 921 922=item Utah 923 924 http://cpan.cs.utah.edu/ 925 ftp://cpan.cs.utah.edu/CPAN/ 926 ftp://mirror.xmission.com/CPAN/ 927 928=item Virginia 929 930 http://mirror.cogentco.com/pub/CPAN/ 931 ftp://mirror.cogentco.com/pub/CPAN/ 932 http://mirror.jmu.edu/pub/CPAN/ 933 ftp://mirror.jmu.edu/pub/CPAN/ 934 http://mirror.us.leaseweb.net/CPAN/ 935 ftp://mirror.us.leaseweb.net/CPAN/ 936 937=item Washington 938 939 http://cpan.llarian.net/ 940 ftp://cpan.llarian.net/pub/CPAN/ 941 942=item Wisconsin 943 944 http://cpan.mirrors.tds.net/ 945 ftp://cpan.mirrors.tds.net/pub/CPAN/ 946 947=back 948 949=back 950 951=head2 Oceania 952 953=over 4 954 955=item Australia 956 957 http://mirror.as24220.net/pub/cpan/ 958 ftp://mirror.as24220.net/pub/cpan/ 959 http://cpan.mirrors.ilisys.com.au/ 960 http://cpan.mirror.digitalpacific.com.au/ 961 ftp://mirror.internode.on.net/pub/cpan/ 962 http://mirror.optusnet.com.au/CPAN/ 963 http://cpan.mirror.serversaustralia.com.au/ 964 http://cpan.uberglobalmirror.com/ 965 http://mirror.waia.asn.au/pub/cpan/ 966 967=item New Caledonia 968 969 http://cpan.lagoon.nc/pub/CPAN/ 970 ftp://cpan.lagoon.nc/pub/CPAN/ 971 http://cpan.nautile.nc/CPAN/ 972 ftp://cpan.nautile.nc/CPAN/ 973 974=item New Zealand 975 976 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ 977 http://cpan.catalyst.net.nz/CPAN/ 978 ftp://cpan.catalyst.net.nz/pub/CPAN/ 979 http://cpan.inspire.net.nz/ 980 ftp://cpan.inspire.net.nz/cpan/ 981 http://mirror.webtastix.net/CPAN/ 982 ftp://mirror.webtastix.net/CPAN/ 983 984=back 985 986=head2 South America 987 988=over 4 989 990=item Argentina 991 992 http://cpan.mmgdesigns.com.ar/ 993 994=item Brazil 995 996 http://cpan.kinghost.net/ 997 http://linorg.usp.br/CPAN/ 998 http://mirror.nbtelecom.com.br/CPAN/ 999 1000=item Chile 1001 1002 http://cpan.dcc.uchile.cl/ 1003 ftp://cpan.dcc.uchile.cl/pub/lang/cpan/ 1004 1005=back 1006 1007=head2 RSYNC Mirrors 1008 1009 rsync://ftp.is.co.za/IS-Mirror/ftp.cpan.org/ 1010 rsync://mirror.ac.za/CPAN/ 1011 rsync://mirror.zol.co.zw/CPAN/ 1012 rsync://mirror.dhakacom.com/CPAN/ 1013 rsync://mirrors.ustc.edu.cn/CPAN/ 1014 rsync://mirrors.xmu.edu.cn/CPAN/ 1015 rsync://kambing.ui.ac.id/CPAN/ 1016 rsync://ftp.jaist.ac.jp/pub/CPAN/ 1017 rsync://mirror.jre655.com/CPAN/ 1018 rsync://ftp.kddilabs.jp/cpan/ 1019 rsync://ftp.nara.wide.ad.jp/cpan/ 1020 rsync://ftp.riken.jp/cpan/ 1021 rsync://mirror.neolabs.kz/CPAN/ 1022 rsync://mirror.qnren.qa/CPAN/ 1023 rsync://ftp.neowiz.com/CPAN/ 1024 rsync://mirror.0x.sg/CPAN/ 1025 rsync://ftp.yzu.edu.tw/pub/CPAN/ 1026 rsync://ftp.ubuntu-tw.org/CPAN/ 1027 rsync://mirrors.digipower.vn/CPAN/ 1028 rsync://cpan.inode.at/CPAN/ 1029 rsync://ftp.byfly.by/CPAN/ 1030 rsync://mirror.datacenter.by/CPAN/ 1031 rsync://ftp.belnet.be/cpan/ 1032 rsync://cpan.mirror.ba/CPAN/ 1033 rsync://mirrors.neterra.net/CPAN/ 1034 rsync://mirrors.netix.net/CPAN/ 1035 rsync://mirror.dkm.cz/cpan/ 1036 rsync://mirrors.nic.cz/CPAN/ 1037 rsync://cpan.mirror.vutbr.cz/cpan/ 1038 rsync://rsync.nic.funet.fi/CPAN/ 1039 rsync://ftp.ciril.fr/pub/cpan/ 1040 rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ 1041 rsync://cpan.mirrors.ovh.net/CPAN/ 1042 rsync://mirror.de.leaseweb.net/CPAN/ 1043 rsync://mirror.euserv.net/cpan/ 1044 rsync://ftp-stud.hs-esslingen.de/CPAN/ 1045 rsync://ftp.gwdg.de/pub/languages/perl/CPAN/ 1046 rsync://ftp.hawo.stw.uni-erlangen.de/CPAN/ 1047 rsync://cpan.mirror.iphh.net/CPAN/ 1048 rsync://mirror.netcologne.de/cpan/ 1049 rsync://ftp.halifax.rwth-aachen.de/cpan/ 1050 rsync://ftp.ntua.gr/CPAN/ 1051 rsync://mirror.met.hu/CPAN/ 1052 rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/ 1053 rsync://rsync.panu.it/CPAN/ 1054 rsync://mirror.as43289.net/CPAN/ 1055 rsync://rsync.cs.uu.nl/CPAN/ 1056 rsync://mirror.nl.leaseweb.net/CPAN/ 1057 rsync://ftp.nluug.nl/CPAN/ 1058 rsync://mirror.transip.net/CPAN/ 1059 rsync://cpan.uib.no/cpan/ 1060 rsync://cpan.vianett.no/CPAN/ 1061 rsync://cpan.perl-hackers.net/CPAN/ 1062 rsync://cpan.perl.pt/cpan/ 1063 rsync://mirrors.m247.ro/CPAN/ 1064 rsync://mirrors.teentelecom.net/CPAN/ 1065 rsync://cpan.webdesk.ru/CPAN/ 1066 rsync://mirror.yandex.ru/mirrors/cpan/ 1067 rsync://mirror.sbb.rs/CPAN/ 1068 rsync://ftp.acc.umu.se/mirror/CPAN/ 1069 rsync://rsync.pirbot.com/ftp/cpan/ 1070 rsync://cpan.ip-connect.vn.ua/CPAN/ 1071 rsync://rsync.mirror.anlx.net/CPAN/ 1072 rsync://mirror.bytemark.co.uk/CPAN/ 1073 rsync://mirror.sax.uk.as61049.net/CPAN/ 1074 rsync://rsync.mirrorservice.org/cpan.perl.org/CPAN/ 1075 rsync://ftp.ticklers.org/CPAN/ 1076 rsync://mirrors.uk2.net/CPAN/ 1077 rsync://CPAN.mirror.rafal.ca/CPAN/ 1078 rsync://mirror.csclub.uwaterloo.ca/CPAN/ 1079 rsync://mirrors.namecheap.com/CPAN/ 1080 rsync://mirrors.syringanetworks.net/CPAN/ 1081 rsync://mirror.team-cymru.org/CPAN/ 1082 rsync://debian.cse.msu.edu/cpan/ 1083 rsync://mirrors-usa.go-parts.com/mirrors/cpan/ 1084 rsync://rsync.hoovism.com/CPAN/ 1085 rsync://mirror.cc.columbia.edu/cpan/ 1086 rsync://noodle.portalus.net/CPAN/ 1087 rsync://mirrors.rit.edu/cpan/ 1088 rsync://mirrors.ibiblio.org/CPAN/ 1089 rsync://cpan.pair.com/CPAN/ 1090 rsync://cpan.cs.utah.edu/CPAN/ 1091 rsync://mirror.cogentco.com/CPAN/ 1092 rsync://mirror.jmu.edu/CPAN/ 1093 rsync://mirror.us.leaseweb.net/CPAN/ 1094 rsync://cpan.mirror.digitalpacific.com.au/cpan/ 1095 rsync://mirror.internode.on.net/cpan/ 1096 rsync://uberglobalmirror.com/cpan/ 1097 rsync://cpan.lagoon.nc/cpan/ 1098 rsync://mirrors.mmgdesigns.com.ar/CPAN/ 1099 1100 1101For an up-to-date listing of CPAN sites, 1102see L<http://www.cpan.org/SITES> or L<ftp://www.cpan.org/SITES>. 1103 1104=head1 Modules: Creation, Use, and Abuse 1105 1106(The following section is borrowed directly from Tim Bunce's modules 1107file, available at your nearest CPAN site.) 1108 1109Perl implements a class using a package, but the presence of a 1110package doesn't imply the presence of a class. A package is just a 1111namespace. A class is a package that provides subroutines that can be 1112used as methods. A method is just a subroutine that expects, as its 1113first argument, either the name of a package (for "static" methods), 1114or a reference to something (for "virtual" methods). 1115 1116A module is a file that (by convention) provides a class of the same 1117name (sans the .pm), plus an import method in that class that can be 1118called to fetch exported symbols. This module may implement some of 1119its methods by loading dynamic C or C++ objects, but that should be 1120totally transparent to the user of the module. Likewise, the module 1121might set up an AUTOLOAD function to slurp in subroutine definitions on 1122demand, but this is also transparent. Only the F<.pm> file is required to 1123exist. See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about 1124the AUTOLOAD mechanism. 1125 1126=head2 Guidelines for Module Creation 1127 1128=over 4 1129 1130=item * 1131 1132Do similar modules already exist in some form? 1133 1134If so, please try to reuse the existing modules either in whole or 1135by inheriting useful features into a new class. If this is not 1136practical try to get together with the module authors to work on 1137extending or enhancing the functionality of the existing modules. 1138A perfect example is the plethora of packages in perl4 for dealing 1139with command line options. 1140 1141If you are writing a module to expand an already existing set of 1142modules, please coordinate with the author of the package. It 1143helps if you follow the same naming scheme and module interaction 1144scheme as the original author. 1145 1146=item * 1147 1148Try to design the new module to be easy to extend and reuse. 1149 1150Try to C<use warnings;> (or C<use warnings qw(...);>). 1151Remember that you can add C<no warnings qw(...);> to individual blocks 1152of code that need less warnings. 1153 1154Use blessed references. Use the two argument form of bless to bless 1155into the class name given as the first parameter of the constructor, 1156e.g.,: 1157 1158 sub new { 1159 my $class = shift; 1160 return bless {}, $class; 1161 } 1162 1163or even this if you'd like it to be used as either a static 1164or a virtual method. 1165 1166 sub new { 1167 my $self = shift; 1168 my $class = ref($self) || $self; 1169 return bless {}, $class; 1170 } 1171 1172Pass arrays as references so more parameters can be added later 1173(it's also faster). Convert functions into methods where 1174appropriate. Split large methods into smaller more flexible ones. 1175Inherit methods from other modules if appropriate. 1176 1177Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>. 1178Generally you can delete the C<eq 'FOO'> part with no harm at all. 1179Let the objects look after themselves! Generally, avoid hard-wired 1180class names as far as possible. 1181 1182Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and 1183C<< $r->func() >> would work. 1184 1185Use autosplit so little used or newly added functions won't be a 1186burden to programs that don't use them. Add test functions to 1187the module after __END__ either using AutoSplit or by saying: 1188 1189 eval join('',<main::DATA>) || die $@ unless caller(); 1190 1191Does your module pass the 'empty subclass' test? If you say 1192C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able 1193to use SUBCLASS in exactly the same way as YOURCLASS. For example, 1194does your application still work if you change: C<< $obj = YOURCLASS->new(); >> 1195into: C<< $obj = SUBCLASS->new(); >> ? 1196 1197Avoid keeping any state information in your packages. It makes it 1198difficult for multiple other packages to use yours. Keep state 1199information in objects. 1200 1201Always use B<-w>. 1202 1203Try to C<use strict;> (or C<use strict qw(...);>). 1204Remember that you can add C<no strict qw(...);> to individual blocks 1205of code that need less strictness. 1206 1207Always use B<-w>. 1208 1209Follow the guidelines in L<perlstyle>. 1210 1211Always use B<-w>. 1212 1213=item * 1214 1215Some simple style guidelines 1216 1217The perlstyle manual supplied with Perl has many helpful points. 1218 1219Coding style is a matter of personal taste. Many people evolve their 1220style over several years as they learn what helps them write and 1221maintain good code. Here's one set of assorted suggestions that 1222seem to be widely used by experienced developers: 1223 1224Use underscores to separate words. It is generally easier to read 1225$var_names_like_this than $VarNamesLikeThis, especially for 1226non-native speakers of English. It's also a simple rule that works 1227consistently with VAR_NAMES_LIKE_THIS. 1228 1229Package/Module names are an exception to this rule. Perl informally 1230reserves lowercase module names for 'pragma' modules like integer 1231and strict. Other modules normally begin with a capital letter and 1232use mixed case with no underscores (need to be short and portable). 1233 1234You may find it helpful to use letter case to indicate the scope 1235or nature of a variable. For example: 1236 1237 $ALL_CAPS_HERE constants only (beware clashes with Perl vars) 1238 $Some_Caps_Here package-wide global/static 1239 $no_caps_here function scope my() or local() variables 1240 1241Function and method names seem to work best as all lowercase. 1242e.g., C<< $obj->as_string() >>. 1243 1244You can use a leading underscore to indicate that a variable or 1245function should not be used outside the package that defined it. 1246 1247=item * 1248 1249Select what to export. 1250 1251Do NOT export method names! 1252 1253Do NOT export anything else by default without a good reason! 1254 1255Exports pollute the namespace of the module user. If you must 1256export try to use @EXPORT_OK in preference to @EXPORT and avoid 1257short or common names to reduce the risk of name clashes. 1258 1259Generally anything not exported is still accessible from outside the 1260module using the ModuleName::item_name (or C<< $blessed_ref->method >>) 1261syntax. By convention you can use a leading underscore on names to 1262indicate informally that they are 'internal' and not for public use. 1263 1264(It is actually possible to get private functions by saying: 1265C<my $subref = sub { ... }; &$subref;>. But there's no way to call that 1266directly as a method, because a method must have a name in the symbol 1267table.) 1268 1269As a general rule, if the module is trying to be object oriented 1270then export nothing. If it's just a collection of functions then 1271@EXPORT_OK anything but use @EXPORT with caution. 1272 1273=item * 1274 1275Select a name for the module. 1276 1277This name should be as descriptive, accurate, and complete as 1278possible. Avoid any risk of ambiguity. Always try to use two or 1279more whole words. Generally the name should reflect what is special 1280about what the module does rather than how it does it. Please use 1281nested module names to group informally or categorize a module. 1282There should be a very good reason for a module not to have a nested name. 1283Module names should begin with a capital letter. 1284 1285Having 57 modules all called Sort will not make life easy for anyone 1286(though having 23 called Sort::Quick is only marginally better :-). 1287Imagine someone trying to install your module alongside many others. 1288 1289If you are developing a suite of related modules/classes it's good 1290practice to use nested classes with a common prefix as this will 1291avoid namespace clashes. For example: Xyz::Control, Xyz::View, 1292Xyz::Model etc. Use the modules in this list as a naming guide. 1293 1294If adding a new module to a set, follow the original author's 1295standards for naming modules and the interface to methods in 1296those modules. 1297 1298If developing modules for private internal or project specific use, 1299that will never be released to the public, then you should ensure 1300that their names will not clash with any future public module. You 1301can do this either by using the reserved Local::* category or by 1302using a category name that includes an underscore like Foo_Corp::*. 1303 1304To be portable each component of a module name should be limited to 130511 characters. If it might be used on MS-DOS then try to ensure each is 1306unique in the first 8 characters. Nested modules make this easier. 1307 1308For additional guidance on the naming of modules, please consult: 1309 1310 http://pause.perl.org/pause/query?ACTION=pause_namingmodules 1311 1312or send mail to the <module-authors@perl.org> mailing list. 1313 1314=item * 1315 1316Have you got it right? 1317 1318How do you know that you've made the right decisions? Have you 1319picked an interface design that will cause problems later? Have 1320you picked the most appropriate name? Do you have any questions? 1321 1322The best way to know for sure, and pick up many helpful suggestions, 1323is to ask someone who knows. The <module-authors@perl.org> mailing list 1324is useful for this purpose; it's also accessible via news interface as 1325perl.module-authors at nntp.perl.org. 1326 1327All you need to do is post a short summary of the module, its 1328purpose and interfaces. A few lines on each of the main methods is 1329probably enough. (If you post the whole module it might be ignored 1330by busy people - generally the very people you want to read it!) 1331 1332Don't worry about posting if you can't say when the module will be 1333ready - just say so in the message. It might be worth inviting 1334others to help you, they may be able to complete it for you! 1335 1336=item * 1337 1338README and other Additional Files. 1339 1340It's well known that software developers usually fully document the 1341software they write. If, however, the world is in urgent need of 1342your software and there is not enough time to write the full 1343documentation please at least provide a README file containing: 1344 1345=over 10 1346 1347=item * 1348 1349A description of the module/package/extension etc. 1350 1351=item * 1352 1353A copyright notice - see below. 1354 1355=item * 1356 1357Prerequisites - what else you may need to have. 1358 1359=item * 1360 1361How to build it - possible changes to Makefile.PL etc. 1362 1363=item * 1364 1365How to install it. 1366 1367=item * 1368 1369Recent changes in this release, especially incompatibilities 1370 1371=item * 1372 1373Changes / enhancements you plan to make in the future. 1374 1375=back 1376 1377If the README file seems to be getting too large you may wish to 1378split out some of the sections into separate files: INSTALL, 1379Copying, ToDo etc. 1380 1381=over 4 1382 1383=item * 1384 1385Adding a Copyright Notice. 1386 1387How you choose to license your work is a personal decision. 1388The general mechanism is to assert your Copyright and then make 1389a declaration of how others may copy/use/modify your work. 1390 1391Perl, for example, is supplied with two types of licence: The GNU GPL 1392and The Artistic Licence (see the files README, Copying, and Artistic, 1393or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT 1394just using the GNU GPL. 1395 1396My personal recommendation, out of respect for Larry, Perl, and the 1397Perl community at large is to state something simply like: 1398 1399 Copyright (c) 1995 Your Name. All rights reserved. 1400 This program is free software; you can redistribute it and/or 1401 modify it under the same terms as Perl itself. 1402 1403This statement should at least appear in the README file. You may 1404also wish to include it in a Copying file and your source files. 1405Remember to include the other words in addition to the Copyright. 1406 1407=item * 1408 1409Give the module a version/issue/release number. 1410 1411To be fully compatible with the Exporter and MakeMaker modules you 1412should store your module's version number in a non-my package 1413variable called $VERSION. This should be a positive floating point 1414number with at least two digits after the decimal (i.e., hundredths, 1415e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version. 1416See L<Exporter> for details. 1417 1418It may be handy to add a function or method to retrieve the number. 1419Use the number in announcements and archive file names when 1420releasing the module (ModuleName-1.02.tar.Z). 1421See perldoc ExtUtils::MakeMaker.pm for details. 1422 1423=item * 1424 1425How to release and distribute a module. 1426 1427If possible, register the module with CPAN. Follow the instructions 1428and links on: 1429 1430 http://www.cpan.org/modules/04pause.html 1431 1432and upload to: 1433 1434 http://pause.perl.org/ 1435 1436and notify <modules@perl.org>. This will allow anyone to install 1437your module using the C<cpan> tool distributed with Perl. 1438 1439By using the WWW interface you can ask the Upload Server to mirror 1440your modules from your ftp or WWW site into your own directory on 1441CPAN! 1442 1443=item * 1444 1445Take care when changing a released module. 1446 1447Always strive to remain compatible with previous released versions. 1448Otherwise try to add a mechanism to revert to the 1449old behavior if people rely on it. Document incompatible changes. 1450 1451=back 1452 1453=back 1454 1455=head2 Guidelines for Converting Perl 4 Library Scripts into Modules 1456 1457=over 4 1458 1459=item * 1460 1461There is no requirement to convert anything. 1462 1463If it ain't broke, don't fix it! Perl 4 library scripts should 1464continue to work with no problems. You may need to make some minor 1465changes (like escaping non-array @'s in double quoted strings) but 1466there is no need to convert a .pl file into a Module for just that. 1467 1468=item * 1469 1470Consider the implications. 1471 1472All Perl applications that make use of the script will need to 1473be changed (slightly) if the script is converted into a module. Is 1474it worth it unless you plan to make other changes at the same time? 1475 1476=item * 1477 1478Make the most of the opportunity. 1479 1480If you are going to convert the script to a module you can use the 1481opportunity to redesign the interface. The guidelines for module 1482creation above include many of the issues you should consider. 1483 1484=item * 1485 1486The pl2pm utility will get you started. 1487 1488This utility will read *.pl files (given as parameters) and write 1489corresponding *.pm files. The pl2pm utilities does the following: 1490 1491=over 10 1492 1493=item * 1494 1495Adds the standard Module prologue lines 1496 1497=item * 1498 1499Converts package specifiers from ' to :: 1500 1501=item * 1502 1503Converts die(...) to croak(...) 1504 1505=item * 1506 1507Several other minor changes 1508 1509=back 1510 1511Being a mechanical process pl2pm is not bullet proof. The converted 1512code will need careful checking, especially any package statements. 1513Don't delete the original .pl file till the new .pm one works! 1514 1515=back 1516 1517=head2 Guidelines for Reusing Application Code 1518 1519=over 4 1520 1521=item * 1522 1523Complete applications rarely belong in the Perl Module Library. 1524 1525=item * 1526 1527Many applications contain some Perl code that could be reused. 1528 1529Help save the world! Share your code in a form that makes it easy 1530to reuse. 1531 1532=item * 1533 1534Break-out the reusable code into one or more separate module files. 1535 1536=item * 1537 1538Take the opportunity to reconsider and redesign the interfaces. 1539 1540=item * 1541 1542In some cases the 'application' can then be reduced to a small 1543 1544fragment of code built on top of the reusable modules. In these cases 1545the application could invoked as: 1546 1547 % perl -e 'use Module::Name; method(@ARGV)' ... 1548or 1549 % perl -mModule::Name ... (in perl5.002 or higher) 1550 1551=back 1552 1553=head1 NOTE 1554 1555Perl does not enforce private and public parts of its modules as you may 1556have been used to in other languages like C++, Ada, or Modula-17. Perl 1557doesn't have an infatuation with enforced privacy. It would prefer 1558that you stayed out of its living room because you weren't invited, not 1559because it has a shotgun. 1560 1561The module and its user have a contract, part of which is common law, 1562and part of which is "written". Part of the common law contract is 1563that a module doesn't pollute any namespace it wasn't asked to. The 1564written contract for the module (A.K.A. documentation) may make other 1565provisions. But then you know when you C<use RedefineTheWorld> that 1566you're redefining the world and willing to take the consequences. 1567 1568=cut 1569 1570read_only_bottom_close_and_rename($out); 1571